mypythontools.utils module — mypythontools 24-08-2021 documentation

# mypythontools.utils module

This module can be used for example in running deploy pipelines or githooks (some code automatically executed before commit). This module can run the tests, edit library version, generate rst files for docs, push to git or deploy app to pypi.

All of that can be done with one function call - with push_pipeline function that run other functions, or you can use functions separately. If you are using other function than push_pipeline, you need to call mypythontools.paths.set_paths() first.

## Examples:

> VS Code Task example

> You can push changes with single click with all the hooks displaying results in your terminal. All params changing every push (like git message or tag) can be configured on the beginning and therefore you don’t need to wait for test finish. Default values can be also used, so in small starting projects, push is actually very fast.

> Create folder utils, create push_script.py inside, add

>     >>> import mypythontools
>     ...
>     >>> if __name__ == "__main__":
>     ...     # Params that are always the same define here. Params that are changing define in IDE when run action.
>     ...     # For example in tasks (command line arguments and argparse will be used).
>     ...     mypythontools.utils.push_pipeline(deploy=True)

> Then just add this task to global tasks.json:

>     {
>     "version": "2.0.0",
>     "tasks": [
>         {
>         "label": "Build app",
>         "type": "shell",
>         "command": "python",
>         "args": ["${workspaceFolder}/utils/build_script.py"],
>         "presentation": {
>             "reveal": "always",
>             "panel": "new"
>         }
>         },
>         {
>         "label": "Hooks & push & deploy",
>         "type": "shell",
>         "command": "python",
>         "args": [
>             "${workspaceFolder}/utils/push_script.py",
>             "--version",
>             "${input:version}",
>             "--commit_message",
>             "${input:commit_message}",
>             "--tag",
>             "${input:tag}",
>             "--tag_mesage",
>             "${input:tag-message}"
>         ],
>         "presentation": {
>             "reveal": "always",
>             "panel": "new"
>         }
>         }
>     ],
>     "inputs": [
>         {
>         "type": "promptString",
>         "id": "version",
>         "description": "Version in __init__.py will be overwiten. Version has to be in format like '1.0.3' three digits and two dots. If None, nothing will happen. If 'increment', than it will be updated by 0.0.1.",
>         "default": "increment"
>         },
>         {
>         "type": "promptString",
>         "id": "commit_message",
>         "description": "Git message for commit.",
>         "default": "New commit"
>         },
>         {
>         "type": "promptString",
>         "id": "tag",
>         "description": "Git tag. If '__version__' is used, then tag from version in __init__.py will be derived. E.g. 'v1.0.1' from '1.0.1'",
>         "default": "__version__"
>         },
>         {
>         "type": "promptString",
>         "id": "tag-message",
>         "description": "Git tag message.",
>         "default": "New version"
>         }
>     ]
>     }

> Git hooks example

> Create folder git_hooks with git hook file - for prec commit name must be pre-commit (with no extension). Hooks in git folder are gitignored by default (and hooks is not visible on first sight).

> Then add hook to git settings - run in terminal (last arg is path (created folder)):

>     $ git config core.hooksPath git_hooks

> In created folder on first two lines copy this:

>     #!/usr/bin/env python
>     # -*- coding: UTF-8 -*-

> Then just import any function from here and call with desired params. E.g.

>     >>> import mypythontools
>     >>> mypythontools.paths.set_paths()
>     >>> version = mypythontools.utils.get_version()  # For example 1.0.2
>     >>> print(version[0].isdigit() == version[2].isdigit() == version[5].isdigit() == (version[1] == '.' == version[3]))
>     True

mypythontools.utils.generate_readme_from_init(git_add=True)

  Because i had very similar things in main __init__.py and in readme. It was to maintain news in code. For better simplicity i prefer write docs once and then generate. One code, two use cases.

  Why __init__? - Because in IDE on mouseover developers can see help. Why README.md? - Good for github.com

  If issuing problems, try paths.set_root() to library path.

  Parameters

    git_add (bool, optional) – Whether to add generated files to stage. False mostly for testing reasons. Defaults to True.

mypythontools.utils.get_version(INIT_PATH=None)

  Get version info from __init__.py file.

  Parameters

    INIT_PATH ((str, Path), optional) – Path to __init__.py file. If None, it’s taken from paths module if used paths.set_paths() before. Defaults to None.

  Returns

    String of version from __init__.py.

  Return type

    str

  Raises

    ValueError – If no __version__ is find. Try set INIT_PATH…

mypythontools.utils.git_push(commit_message, tag='__version__', tag_message='New version')

  Stage all changes, commit, add tag and push. If tag = ‘__version__’, than tag is infered from __init__.py.

  Parameters

    - commit_message (str) – Commit message.

    - tag (str, optional) – Define tag used in push. If tag is ‘__version__’, than is automatically generated from __init__ version. E.g from ‘1.0.2’ to ‘v1.0.2’. Defaults to ‘__version__’.

    - tag_message (str, optional) – Message in anotated tag. Defaults to ‘New version’.

mypythontools.utils.push_pipeline(test=True, test_options={}, version='increment', sphinx_docs=True, push_git=True, commit_message='New commit', tag='__version__', tag_mesage='New version', deploy=False)

  Run pipeline for pushing and deploying app. Can run tests, generate rst files for sphinx docs, push to github and deploy to pypi. All params can be configured not only with function params, but also from command line with params and therefore callable from terminal and optimal to run from IDE (for example with creating simple VS Code task).

  Check utils module docs for implementation example.

  Parameters

    - test (bool, optional) – Whether run pytest tests. Defaults to True.

    - test_options (dict, optional) – Parameters of tests function e.g. {“test_coverage”: True, “verbose”: False, “use_virutalenv”:True}. Defaults to {}.

    - version (str, optional) – New version. E.g. ‘1.2.5’. If ‘increment’, than it’s auto incremented. E.g from ‘1.0.2’ to ‘v1.0.3’. If None, then version is not changed. ‘Defaults to “increment”.

    - sphinx_docs ((bool, list), optional) – Whether generate sphinx apidoc and generate rst files for documentation. Some files in docs source can be deleted - check sphinx_docs docstrings for details and insert exclude_paths list if have some extra files other than [‘conf.py’, ‘index.rst’, ‘_static’, ‘_templates’]. Defaults to True.

    - push_git (bool, optional) – Whether push repository on git with git_message, tag and tag message. Defaults to True.

    - git_message (str, optional) – Git message. Defaults to ‘New commit’.

    - tag (str, optional) – Used tag. If None, not tag will be pushed. If tag is ‘__version__’, than updated version from __init__ is used. Defaults to __version__.

    - tag_mesage (str, optional) – Tag message. Defaults to New version.

    - deploy (bool, optional) – Whether deploy to PYPI. Defaults to False.

  Example

  Recommended use is from IDE (for example with Tasks in VS Code). Check utils docs for how to use it. You can also use it from python…

      >>> import mypythontools
      ...
      >>> if __name__ == "__main__":
      ...     mypythontools.utils.push_pipeline(deploy=True)  # All the params that change everytime configure for example in VS Code tasks.

mypythontools.utils.set_version(version='increment')

  Change your version in your __init__.py file.

  Parameters

    version (str, optional) – If version is ‘increment’, it will increment your __version__ in you __init__.py by 0.0.1. Defaults to “increment”.

  Raises

    ValueError – If no __version__ is find. Try set INIT_PATH via paths.set_paths…

mypythontools.utils.sphinx_docs_regenerate(docs_path=None, build_locally=False, git_add=True, exclude_paths=[], delete=['modules.rst'])

  This will generate all rst files necessary for sphinx documentation generation with sphinx-apidoc. It automatically delete removed and renamed files.

  Note

  All the files except [‘conf.py’, ‘index.rst’, ‘_static’, ‘_templates’] will be deleted!!! Because if some files would be deleted or renamed, rst would stay and html was generated. If you have some extra files or folders in docs source - add it to exclude_paths list.

  Function suppose sphinx build and source in separate folders…

  Parameters

    - docs_path ((str, Path), optional) – Where source folder is. Usually infered automatically. Defaults to None.

    - build_locally (bool, optional) – If true, build folder with html files locally. Defaults to False.

    - git_add (bool, optional) – Whether to add generated files to stage. False mostly for testing reasons. Defaults to True.

    - exclude_paths (list, optional) – List of files and folder names that will not be deleted. [‘conf.py’, ‘index.rst’, ‘_static’, ‘_templates’] are excluded by default. Defaults to [].

    - delete (list, optional) – If delete some files (for example to have no errors in sphinx build for unused modules)

  Note

  Function suppose structure of docs like:

      -- docs
      -- -- source
      -- -- -- conf.py
      -- -- make.bat

  If you are issuing error, try set project root path with set_root