Python Humble Utils Documentation¶

Contents:

Python Humble Utils¶

Join the chat at https://gitter.im/webyneter/python-humble-utils

Python utils for everyday use.

Documentation.
Please, open issues before sending emails to the maintainers: You will get a much faster response!

Feature Areas¶

File operations.
File/directory paths extraction.
File/directory paths randomization.
String case conversions.
Python class convenience shortcuts.
py.test fixtures and helpers.

Installation¶

$ pip install python-humble-utils

or install from sources:

$ python setup.py install

Refer to Installation for detailed instructions.

Usage¶

import os
from pathlib import Path

from python_humble_utils.filesystem import yield_file_paths
from python_humble_utils.strings import camel_or_pascal_case_to_snake_case


# ...

file_paths = yield_file_paths(
    dir_path=Path("dir") / "with" / "scripts",
    allowed_file_extensions=(".sh", ".bash"),
    recursively=True
)
assert set(file_paths) == set(("s1.sh", "s2.bash", "s3.bash"))

s = camel_or_pascal_case_to_snake_case("camelCasedString")
assert s == "camel_cased_string"

s = camel_or_pascal_case_to_snake_case("PascalCasedString")
assert s == "pascal_cased_string"

# ...

Contributing¶

Your contributions are very much welcome! Refer to Contributing for more details.

Code of Conduct¶

All those using python-humble-utils, including its codebase and project management ecosystem are expected to follow the Python Community Code of Conduct.

Acknowledgements¶

This package was initially scaffolded via Cookiecutter with audreyr/cookiecutter-pypackage template.

python_humble_utils package¶

Subpackages¶

python_humble_utils.vendor package¶

Submodules¶

python_humble_utils.vendor.pytest module¶

python_humble_utils.vendor.pytest.generate_tmp_file_path(tmpdir_factory, file_name_with_extension: str, tmp_dir_path: Optional[pathlib.Path] = None) → pathlib.Path[source]¶

Generate file path relative to a temporary directory.

Parameters:	tmpdir_factory – py.test’s tmpdir_factory fixture. file_name_with_extension – file name with extension e.g. file_name.ext. tmp_dir_path – path to directory (relative to the temporary one created by tmpdir_factory) where the generated file path should reside. # noqa
Returns:	file path.

Module contents¶

Submodules¶

python_humble_utils.classes module¶

python_humble_utils.classes.get_all_subclasses(cls: Type[CT_co], including_self: bool = False) → Collection[Type[CT_co]][source]¶

Get all subclasses.

Parameters:

cls – class to lookup subclasses of.
including_self – whether or not the the :param cls: itself is to be accounted for.

Returns:

param cls:	subclasses.

python_humble_utils.filesystem module¶

python_humble_utils.filesystem.create_or_update_file(file_path: str, file_content: str = '', file_content_encoding: str = 'utf-8') → None[source]¶

Create or update file.

Parameters:	file_path – path to the file. file_content – file content. file_content_encoding – file content encoding e.g. latin-1.

python_humble_utils.filesystem.generate_random_dir_path(root_dir_path: Optional[pathlib.Path] = None, subdir_count: int = 0, random_string_generator: Optional[Callable[[], str]] = None) → pathlib.Path[source]¶

Generate a random directory path.

Parameters:	root_dir_path – root dir path; by default, the current dir path is used subdir_count – a number of subdirectories to generate in the directory root. random_string_generator – random number generator; by default, the UUID4 hex is used
Returns:	directory root path.

python_humble_utils.filesystem.read_file(file_path: str, as_single_line: bool = False) → str[source]¶

Read file content.

Parameters:	file_path – path to the file. as_single_line – whether or not the file is to be read as a single line.
Returns:	file content.

python_humble_utils.filesystem.yield_file_paths(dir_path: pathlib.Path, allowed_file_extensions: Collection[str], recursively: bool = False) → Iterable[pathlib.Path][source]¶

Yield file paths.

Parameters:	dir_path – path to the containing directory. allowed_file_extensions – file extensions to match against e.g. [‘.abc’, ‘.def’]. recursively – whether or not the directory is to be recursively traversed.
Returns:	file paths.

python_humble_utils.objects module¶

python_humble_utils.objects.flatten(obj: Any, flatten_dicts_by_values: bool = True, coerce: Optional[Callable[[T], M]] = None) → Iterable[M][source]¶

Flatten an arbitrarily complex object.

Parameters:	obj – an obj to flatten. flatten_dicts_by_values – if True, mapping will be flattened by values, otherwise by keys. coerce – a callable used to coerce items of the resulting iterable to
Returns:	a recursively-constructed iterable of the object’s constituents.

python_humble_utils.objects.get_all_instances(cls: Type[T]) → Sequence[T][source]¶

Get all class instances.

python_humble_utils.strings module¶

python_humble_utils.strings.camel_or_pascal_case_to_snake_case(s: str) → str[source]¶

Convert camelCased or PascalCased string to snake_case.

Based on https://stackoverflow.com/a/1176023/1557013.

Parameters:	s – string in camelCase or PascalCase.
Returns:	string in snake_case.

python_humble_utils.strings.camel_or_pascal_case_to_space_delimited(s: str) → str[source]¶

Convert camelCased or PascalCased string to space-delimited.

Based on https://stackoverflow.com/a/9283563/1557013.

Parameters:	s – string in camelCase or PascalCase.
Returns:	space-delimited string.

Module contents¶

Installation¶

Note

The commands below are presumed to be run relative to the project root unless explicitly stated otherwise. ./ also refers to the project root.

From PyPI¶

To install the latest release, run

$ pip install python-humble-utils

Or, install a specific version via

$ pip install python-humble-utils==<version>

If you don’t have pip installed, this Python installation guide can guide you through the process.

From Sources¶

Obtain sources

cloning the repository:

$ git clone git://github.com/webyneter/python-humble-utils

or, downloading a tarball:

$ curl -OL https://github.com/webyneter/python-humble-utils/tarball/master

Install via:
```
$ python setup.py install
```

Usage¶

import os
from pathlib import Path

from python_humble_utils.filesystem import yield_file_paths
from python_humble_utils.strings import camel_or_pascal_case_to_snake_case


# ...

file_paths = yield_file_paths(
    dir_path=Path("dir") / "with" / "scripts",
    allowed_file_extensions=(".sh", ".bash"),
    recursively=True
)
assert set(file_paths) == set(("s1.sh", "s2.bash", "s3.bash"))

s = camel_or_pascal_case_to_snake_case("camelCasedString")
assert s == "camel_cased_string"

s = camel_or_pascal_case_to_snake_case("PascalCasedString")
assert s == "pascal_cased_string"

# ...

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Note

The commands below are presumed to be run relative to the project root unless explicitly stated otherwise. ./ also refers to the project root.

Ways You Can Help Us¶

Report Bugs¶

Create an issue corresponding to the bug you have found complying with the project’s issue template.

Fix Bugs¶

Look through the GitHub issues: Anything tagged with bug and without an Assignee is open to whoever wants to implement it.

Make sure to submit clean, concise, well-tested pull requests only, so it is easier for contributors to review it; strive to deliver as short and atomic pull requests as possible as this will dramatically increase the likelihood of those being merged.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with enhancement and/or help wanted and/or without an Assignee is open to whoever wants to implement it.

Write Documentation¶

We could always use more documentation, whether as part of the official docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue.

If you are proposing a feature,

explain in detail how it would work;
keep the scope as narrow as possible, to make it easier to implement;
remember that this is a volunteer-driven project, so contributions are welcome!

Workflow¶

See Developing Locally for detailed instructions on setting up local environment.

Oncer you are all set up,

create a branch:

$ git checkout -b <issue id>-<issue title>

make the contribution;
follow Running tox with Multiple Python Distributions to run tests comprehensively;

commit changes to the branch:

$ git add .
$ git commit -m "<detailed description of your changes>"

push the branch to GitHub:

$ git push origin <issue id>-<issue title>

submit a pull request via GitHub or any other git GUI tool you prefer.

Guidelines¶

Upon submission, make sure the PR meets these guidelines:

the PR does not decrease code coverage (unless there is a very specific reason to);
the docs (both programmatic and manual) are updated, if needed.

Developing Locally¶

Note

The commands below are presumed to be run relative to the project root unless explicitly stated otherwise. ./ also refers to the project root.

Environment Setup¶

Fork us on GitHub.

Clone your fork locally:

$ git clone git@github.com:<your username>/python-humble-utils.git

Create a virtualenv ; assuming you have virtualenvwrapper installed, this is how you do it:

$ mkvirtualenv python_humble_utils
$ cd <cloned project root>
$ setvirtualenvproject

Initialize environment:
```
$ python setup.py develop
```

Scenarios¶

Updating Requirements¶

Project requirements must be declared and pinned in ./requirements*.txt.

To install/upgrade/uninstall dependencies into/in/from the environment:

$ make install

Running `tox` with Multiple Python Distributions¶

Running tox locally requires a number of Python distributions to be available, which is a challenge, to say the least. pyenv helps overcome this major obstacle.

Follow pyenv installation instructions to install pyenv system-wide.
Install all versions of Python the project is tested against by tox (see ./tox.ini).
Run tox:
```
$ make test-all
```

Project Makefile¶

Note

The commands below are presumed to be run relative to the project root unless explicitly stated otherwise. ./ also refers to the project root.

To facilitate smooth development workflow, we provide a Makefile defining a number of convenience commands.

clean running
1. clean-build (build artifact removal);
2. clean-pyc (compilation artifact removal);
3. clean-test (test and coverage artifact removal).
Specifically:
$ make clean $ make clean-build $ make clean-pyc $ make clean-test
lint checking codebase compliance with PEP8 via flake8:
```
$ make lint
```
test running py.test:
```
$ make test
```
test-all running tox:
```
$ make test-all
```
coverage running coverage:
```
$ make coverage
```
docs generating project docs via Sphinx:
```
$ make docs
```
servedocs serving docs live via watchdog:
```
$ make servedocs
```
setup-release packaging and releasing the project to PyPI:
```
$ make setup-release
```
setup-dist builds source and wheel packages via setuptools:
```
$ make setup-dist
```
setup-install installing the package to the current environment:
```
$ make setup-install
```
install keeping local environment dependencies in sync with those defined in ./requirements*.txt:
```
$ make install
```

Credits¶

Development Lead¶

Nikita P. Shupeyko <webyneter@gmail.com>

Contributors¶

None yet. Why not be the first?

History¶

v3.0.1¶

v3.0.1.

v3.0.0¶

v3.0.0.

Breaking changes:

The following functions have been removed as part of the Remove redundant utilities/utilities making no sense effort:
- extract_file_name_with_extension
- extract_file_name_and_extension
- extract_file_dir_path
- parse_tuple_from_string
- generate_hex_uuid_4
- generate_random_file_name_with_extension
- get_class_name
- get_class_qualname
Package structure has been altered.
Drop support for Python 3.5.

Other changes:

Update the docs.
Switch from Python 3.6+ typing.Collection back to typing.Sequence for backward compatibility with Python 3.5.
Support Python 3.8.
Switch to native Python paths.
Support Python 3.7.
Upgrade all dependencies to the latest versions to date.

First release on PyPI.

Python Humble Utils Documentation¶