wads.pack

Utils to package and publish.

The typical sequence of the methodic and paranoid could be something like this:

python pack.py current-configs  # see what you got
python pack.py increment-configs-version  # update (increment the version and write that in setup.cfg
python pack.py current-configs-version  # see that it worked
python pack.py current-configs  # ... if you really want to see the whole configs again (you're really paranoid)
python pack.py run-setup  # see that it worked
python pack.py twine-upload-dist  # publish
# and then go check things work...

If you’re crazy (or know what you’re doing) just do

python pack.py go

wads.pack.check_in(commit_message: str, *, work_tree: str = '.', git_dir: str | None = None, auto_choose_default_action: bool = False, bypass_docstring_validation: bool = False, bypass_tests: bool = False, bypass_code_formatting: bool = False, verbose: bool = False, pre_git_hooks: Sequence[str] = ())[source]

Validate, normalize, stage, commit and push your local changes to a remote repository.

Parameters:

commit_message (str) – Your commit message
work_tree (str, optional) – The relative or absolute path of the working directory. Defaults to ‘.’.
git_dir (str, optional) – The relative or absolute path of the git directory. If None, it will be taken to be “{work_tree}/.git/”. Defaults to None.
auto_choose_default_action (bool, optional) – Set to True if you don’t want to be prompted and automatically select the default action. Defaults to False.
bypass_docstring_validation (bool, optional) – Set to True if you don’t want to check if a docstring exists for every module, class and function. Defaults to False.
bypass_tests (bool, optional) – Set to True if you don’t want to run doctests and other tests. Defaults to False.
bypass_code_formatting (bool, optional) – Set to True if you don’t want the code to be automatically formatted using axblack. Defaults to False.
verbose (bool, optional) – Set to True if you want to log extra information during the process. Defaults to False.
pre_git_hooks – A sequence of git commands to run before the git commit. Defaults to ().

wads.pack.current_pypi_version(pkg_dir: str) → str | None[source]

Return version of package on pypi.python.org using json.

>>> current_pypi_version('wads')  
'0.1.19'

wads.pack.extract_pkg_dir_and_name(pkg_spec: str | ModuleType | Path, *, validate: bool = True) → Tuple[str, str][source]

Extracts the pkg_dir and pkg_dirname from the input pkg_spec. Optionally validates the pkg_dir is actually one (has a pkg_name/__init__.py file)

Also processes input to get a path from a pathlib.Path object, or a module object, or a module/package name string.

pkg_spec can be an imported package (must be a locally developped package) whose name and containing directory is the same):

>>> import wads
>>> extract_pkg_dir_and_name(wads)  
(.../wads', 'wads')

You can also just specify the name of the package (it will be imported):

>>> extract_pkg_dir_and_name('wads')  
('.../wads', 'wads')

Or you can specify the path to the package directory explicitly:

>>> extract_pkg_dir_and_name('/home/user/projects/wads')  
('/home/user/projects/wads', 'wads')

wads.pack.folders_that_have_init_py_files(pkg_dir: str) → List[str][source]

Get a list of folders in the package directory that have an __init__.py file.

>>> folders_that_have_init_py_files('/home/user/projects/wads')  
['wads', 'wads/util', 'wads/pack', 'wads/docs_gen']

wads.pack.get_module_path(module: ModuleType) → str[source]

Get the path to the directory containing the module’s code file.

>>> import os
>>> get_module_path(os)  
'/usr/lib/python3.8'
>>> import sklearn  
>>> get_module_path(sklearn)  
'/usr/local/lib/python3.8/dist-packages/sklearn'
>>> import local_package  
>>> get_module_path(local_package)  
'/home/user/projects/local_package/local_package'

wads.pack.get_name_from_configs(pkg_dir, *, assert_exists=True)[source]: Get name from local setup.cfg (metadata section)

wads.pack.get_pkg_name(pkg_spec: str | ModuleType | Path, validate=True) → str[source]: Get the name of the package from a package name, module object or path. Optionally validates some naming rules.

wads.pack.go(pkg_dir, *, version=None, publish_docs_to=None, verbose: bool = True, skip_git_commit: bool = False, answer_yes_to_all_prompts: bool = False, twine_upload_options_str: str = '', keep_dist_pkgs=False, commit_message='')[source]

Update version, package and deploy: Runs in a sequence: increment_configs_version, update_setup_cfg, run_setup, twine_upload_dist

Parameters:

version – The desired version (if not given, will increment the current version
verbose – Whether to print stuff or not
skip_git_commit – Whether to skip the git commit and push step
answer_yes_to_all_prompts – If you do git commit and push, whether to ask confirmation after showing status

wads.pack.goo(pkg_dir, commit_message, *, git_dir=None, auto_choose_default_action=False, bypass_docstring_validation=False, bypass_tests=False, bypass_code_formatting=False, verbose=False)[source]

Validate, normalize, stage, commit and push your local changes to a remote repository.

Parameters:

pkg_dir (str, optional) – The relative or absolute path of the working directory. Defaults to ‘.’.
commit_message (str) – Your commit message
git_dir (str, optional) – The relative or absolute path of the git directory. If None, it will be taken to be “{work_tree}/.git/”. Defaults to None.
auto_choose_default_action (bool, optional) – Set to True if you don’t want to be prompted and automatically select the default action. Defaults to False.
bypass_docstring_validation (bool, optional) – Set to True if you don’t want to check if a docstring exists for every module, class and function. Defaults to False.
bypass_tests (bool, optional) – Set to True if you don’t want to run doctests and other tests. Defaults to False.
bypass_code_formatting (bool, optional) – Set to True if you don’t want the code to be automatically formatted using axblack. Defaults to False.
verbose (bool, optional) – Set to True if you want to log extra information during the process. Defaults to False.

wads.pack.highest_pypi_version(pkg_dir: str, *, name: str | None = None, use_requests=True) → List[str][source]

Return version of package on pypi.python.org using json.

>>> highest_pypi_version('wads')  
'0.1.19'

Parameters:: package – Name of the package
Returns:: A version (string) or None if there was an exception (usually means there

wads.pack.http_get_json(url, use_requests=True) → dict | None[source]: Make ah http request to url and get json, and return as python dict

wads.pack.increment_configs_version(pkg_dir, *, version=None)[source]: Increment version setup.cfg.

wads.pack.postprocess_ini_section_items(items: Mapping | Iterable) → Generator[source]

Transform newline-separated string values into actual list of strings (assuming that intent)

>>> section_from_ini = {
...     'name': 'wads',
...     'keywords': '\n\tpackaging\n\tpublishing'
... }
>>> section_for_python = dict(postprocess_ini_section_items(section_from_ini))
>>> section_for_python
{'name': 'wads', 'keywords': ['packaging', 'publishing']}

wads.pack.preprocess_ini_section_items(items: Mapping | Iterable) → Generator[source]

Transform list values into newline-separated strings, in view of writing the value to a ini formatted section

>>> section = {
...     'name': 'wads',
...     'keywords': ['documentation', 'packaging', 'publishing']
... }
>>> for_ini = dict(preprocess_ini_section_items(section))
>>> print('keywords =' + for_ini['keywords'])  
keywords =
    documentation
    packaging
    publishing

wads.pack.process_missing_module_docstrings(*, pkg_dir: str, action='input', exceptions=(), docstr_template='"""\n{user_input}\n"""\n')[source]

Goes through modules of package, sees which ones don’t have docstrings, and gives you the option to write one.

The function will go through all .py files (except those mentioned in exceptions), check if there’s a module docstring (that is, that the first non-white characters are triple-quotes (double or single)).

What happens with that depends on the action argument,

If action='list', those modules missing docstrings will be listed. If action='count', the count of those modules missing docstrings will be returned.

If action='input', for every module you’ll be given the option to enter a SINGLE LINE module docstring (though you could include multi-lines with n). Just type the docstring you want and hit enter to go to the next module with missing docstring. Or, you can also:

type exit, or e: To exit this process

type skip, or s: To skip the module and go to the next

type funcs, or f: To see a print out of functions, classes, and methods

just hit enter, to get some lines of code (the first, then the next, etc.)

enter a number, or a number:number, to specify what lines you want to see printed

Printing lines helps you write an informed module docstring

:keyword module, docstr, docstrings, module doc strings

wads.pack.read_and_resolve_setup_configs(pkg_dir: str, *, new_deploy=False, version=None, assert_names=True)[source]

make setup params and call setup

Parameters:

pkg_dir – Directory where the pkg is (which is also where the setup.cfg is)
new_deploy – whether this setup for a new deployment (publishing to pypi) or not
version – The version number to set this up as. If not given will look at setup.cfg[metadata] for one, and if not found there will use the current version (requesting pypi.org) and bump it if the new_deploy flag is on

wads.pack.run_setup(pkg_dir)[source]: Run python setup.py sdist bdist_wheel

wads.pack.set_version(pkg_dir, version)[source]: Update version setup.cfg

wads.pack.setup_cfg_version(pkg_spec: str | ModuleType | Path)[source]: Get version from setup.cfg file.

wads.pack.sorted_versions(strings: Iterable[str], version_patch_prefix='')[source]: Filter out and return version strings in (versioning) descending order.

wads.pack.twine_upload_dist(pkg_dir, *, options_str=None)[source]: Publish to pypi. Runs python -m twine upload dist/*

wads.pack.update_setup_cfg(pkg_dir, *, new_deploy=False, version=None, verbose=True)[source]: Update setup.cfg. If version is not given, will ask pypi (via http request) what the current version is, and increment that.

wads.pack.validate_versions(versions: dict, action_when_not_valid=<function raise_error>) → dict[source]

Validate versions from different sources.

You get the versions input from the versions_from_different_sources function.

Parameters:

versions – A dictionary with the versions from different sources
action_when_not_valid – A function that will be called when the versions are not valid Default is to raise a ValueError with the error message. Another option is to print the error message, log it, or issue a warning.

Returns:

The versions if they are valid

wads.pack.versions_from_pypi(pkg_dir: str, *, name: str | None = None, use_requests=True) → str | None[source]

Return version of package on pypi.python.org using json.

Parameters:: package – Name of the package
Returns:: A version (string) or None if there was an exception (usually means there