{"id":13448145,"url":"https://github.com/ionelmc/cookiecutter-pylibrary","last_synced_at":"2025-05-14T13:05:52.825Z","repository":{"id":39310284,"uuid":"20260001","full_name":"ionelmc/cookiecutter-pylibrary","owner":"ionelmc","description":"Enhanced cookiecutter template for Python libraries.","archived":false,"fork":false,"pushed_at":"2025-03-22T14:37:34.000Z","size":1250,"stargazers_count":1266,"open_issues_count":11,"forks_count":206,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-04-12T13:57:31.790Z","etag":null,"topics":["cookiecutter","cookiecutter-template","python","template"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ionelmc.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-05-28T14:14:29.000Z","updated_at":"2025-04-08T23:08:14.000Z","dependencies_parsed_at":"2023-02-12T10:16:05.026Z","dependency_job_id":"62bd56c7-008d-4c6c-b136-0e160a9a8afc","html_url":"https://github.com/ionelmc/cookiecutter-pylibrary","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fcookiecutter-pylibrary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fcookiecutter-pylibrary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fcookiecutter-pylibrary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ionelmc%2Fcookiecutter-pylibrary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ionelmc","download_url":"https://codeload.github.com/ionelmc/cookiecutter-pylibrary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149946,"owners_count":22022851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookiecutter","cookiecutter-template","python","template"],"created_at":"2024-07-31T05:01:36.953Z","updated_at":"2025-05-14T13:05:52.786Z","avatar_url":"https://github.com/ionelmc.png","language":"Python","funding_links":[],"categories":["Python","HarmonyOS","Project Templates"],"sub_categories":["Windows Manager"],"readme":"======================\ncookiecutter-pylibrary\n======================\n\nCookiecutter_ template for a Python library.\n\n*Notes*:\n\n* This is largely designed to address this `blog post about packaging python\n  libraries \u003chttps://blog.ionelmc.ro/2014/05/25/python-packaging/\u003e`_.\n\n  * ... and it will save you from `packaging pitfalls\n    \u003chttps://blog.ionelmc.ro/2014/06/25/python-packaging-pitfalls/\u003e`_.\n* There's a bare library using this template (if you're curious about the final\n  result): https://github.com/ionelmc/python-nameless.\n* If you have a web application (not a library) you might want to take a look at\n  `django-docker \u003chttps://github.com/evozon/django-docker\u003e`_.\n\n.. contents:: Table of Contents\n\nFeatures\n--------\n\nThis is an \"all inclusive\" sort of template.\n\n* Choice of various licenses.\n* Tox_ for managing test environments for Python 2.7, 3.7+, PyPy etc.\n* Pytest_ or Nose_ for testing Python 2.7, 3.7+, PyPy etc.\n* *Optional* support for creating a tests matrix out of dependencies and python versions.\n* Travis-CI_ and AppVeyor_ for continuous testing.\n* Coveralls_ or Codecov_ for coverage tracking (using Tox_).\n* Documentation with Sphinx_, ready for ReadTheDocs_.\n* Configurations for:\n\n  * isort_\n  * bumpversion_ (bump2version_ required)\n\n* Support for C extensions (including coverage measurement for the C code). See c_extension_support_.\n* Packaging and code quality checks. This template comes with a tox environment (``check``) that will:\n\n  * Check if your ``README.rst`` is valid.\n  * Check if the ``MANIFEST.in`` has any issues.\n\nRequirements\n------------\n\nProjects using this template have these minimal dependencies:\n\n* Cookiecutter_ - just for creating the project\n* Tox_ - for running the tests\n* Setuptools_ - for building the package, wheels etc. Now-days Setuptools is widely available, it shouldn't pose a\n  problem :)\n\nTo get quickly started on a new system, just `install setuptools\n\u003chttps://pypi.org/project/setuptools#installation-instructions\u003e`_ and then `install pip\n\u003chttps://pip.pypa.io/en/latest/installing.html\u003e`_. That's the bare minimum to required install Tox_ and Cookiecutter_. To install\nthem, just run this in your shell or command prompt::\n\n  pip install tox cookiecutter\n\nUsage and options\n-----------------\n\nThis template is more involved than the regular `cookiecutter-pypackage\n\u003chttps://github.com/audreyr/cookiecutter-pypackage\u003e`_.\n\nFirst generate your project::\n\n  cookiecutter gh:ionelmc/cookiecutter-pylibrary\n\nYou will be asked for these fields:\n\n.. note:: Fields that work together usually use the same prefix. If you answer \"no\" on the first one then the rest\n   won't have any effect so just ignore them. Maybe in the future cookiecutter will allow option hiding or something\n   like a wizard.\n\n.. list-table::\n    :header-rows: 1\n\n    * - Field\n      - Default\n      - Description\n\n    * - ``full_name``\n      - .. code:: python\n\n            \"Ionel Cristian Maries\"\n      - Main author of this library or application (used in ``AUTHORS.rst`` and ``setup.py``).\n\n        Can be set in your ``~/.cookiecutterrc`` config file.\n\n    * - ``email``\n      - .. code:: python\n\n            \"contact@ionelmc.ro\"\n      - Contact email of the author (used in ``AUTHORS.rst`` and ``setup.py``).\n\n        Can be set in your ``~/.cookiecutterrc`` config file.\n\n    * - ``website``\n      - .. code:: python\n\n            \"https://blog.ionelmc.ro\"\n      - Website of the author (used in ``AUTHORS.rst``).\n\n        Can be set in your ``~/.cookiecutterrc`` config file.\n\n    * - ``repo_username``\n      - .. code:: python\n\n            \"ionelmc\"\n      - GitHub user name of this project (used for GitHub link).\n\n        Can be set in your ``~/.cookiecutterrc`` config file.\n\n    * - ``project_name``\n      - .. code:: python\n\n            \"Nameless\"\n      - Verbose project name, used in headings (docs, readme, etc).\n\n    * - ``repo_hosting_domain``\n      - .. code:: python\n\n            \"github.com\"\n      - Use ``\"no\"`` for no hosting (various links will disappear). You can also use ``\"gitlab.com\"`` and such but various\n        things will be broken (like Travis configuration).\n\n    * - ``repo_name``\n      - .. code:: python\n\n            \"python-nameless\"\n      - Repository name on GitHub (and project's root directory name).\n\n    * - ``package_name``\n      - .. code:: python\n\n            \"nameless\"\n      - Python package name (whatever you would import).\n\n    * - ``distribution_name``\n      - .. code:: python\n\n            \"nameless\"\n      - PyPI distribution name (what you would ``pip install``).\n\n    * - ``module_name``\n      - .. code:: python\n\n            \"core\"\n      - This template assumes there's going to be an \"implementation\" module inside your package.\n\n    * - ``project_short_description``\n      - .. code:: python\n\n            \"An example package [...]\"\n      - One line description of the project (used in ``README.rst`` and ``setup.py``).\n\n    * - ``release_date``\n      - .. code:: python\n\n            \"today\"\n      - Release date of the project (ISO 8601 format) default to today (used in ``CHANGELOG.rst``).\n\n    * - ``year``\n      - .. code:: python\n\n            \"now\"\n      - Copyright year (used in Sphinx ``conf.py``).\n\n    * - ``version``\n      - .. code:: python\n\n            \"0.1.0\"\n      - Release version (see ``.bumpversion.cfg`` and in Sphinx ``conf.py``).\n\n    * - ``c_extension_support``\n      - .. code:: python\n\n            \"no\"\n      - .. _c_extension_support:\n\n        Support C extensions (will slightly change the outputted ``setup.py``). Available options:\n\n        * ``\"yes\"`` - to generate a Python C extension\n        * ``\"cffi\"`` - to generate CFFI bindings against a C library\n        * ``\"cython\"`` - to generate a Cython extension\n\n\n    * - ``c_extension_optional``\n      - .. code:: python\n\n            \"no\"\n      - Make C extensions optional (will allow your package to install even if extensions can't be compiled)\n    * - ``test_matrix_separate_coverage``\n      - .. code:: python\n\n            \"no\"\n      - Enable this to have a separate env for measuring coverage. Indicated if you want to run doctests or collect tests\n        from ``src`` with pytest.\n    * - ``setup_py_uses_setuptools_scm``\n      - .. code:: python\n\n            \"no\"\n      - Enables the use of `setuptools-scm \u003chttps://pypi.org/project/setuptools-scm/\u003e`_. You can continue using\n        bumpversion_ with this enabled.\n    * - ``tests_inside_package``\n      - .. code:: python\n\n            \"no\"\n      - Collect tests that are inside the package (in other works, tests that are installed with the package).\n\n        The outside of package `tests` directory will still exist and be collected.\n    * - ``command_line_interface``\n      - .. code:: python\n\n            \"plain\"\n      - Option to enable a CLI (a bin/executable file). Available options:\n\n        * ``plain`` - a very simple command.\n        * ``argparse`` - a command implemented with ``argparse``.\n        * ``click`` - a command implemented with `click \u003chttp://click.pocoo.org/\u003e`_ - which you can use to build more complex commands.\n        * ``no`` - no CLI at all.\n\n    * - ``command_line_interface_bin_name``\n      - .. code:: python\n\n            \"nameless\"\n      - Name of the CLI bin/executable file (set the console script name in ``setup.py``).\n\n    * - ``license``\n      - .. code:: python\n\n            \"BSD license\"\n      - License to use. Available options:\n\n        * BSD license\n        * MIT license\n        * ISC license\n        * Apache Software License 2.0\n\n        What license to pick? https://choosealicense.com/\n\n    * - ``coveralls``\n      - .. code:: python\n\n            \"no\"\n      - Enable pushing coverage data to Coveralls_ and add badge in ``README.rst``.\n\n    * - ``codecov``\n      - .. code:: python\n\n            \"yes\"\n      - Enable pushing coverage data to Codecov_ and add badge in ``README.rst``.\n\n        **Note:** Doesn't support pushing C extension coverage yet.\n\n    * - ``scrutinizer``\n      - .. code:: python\n\n            \"no\"\n      - Add a Scrutinizer_ badge in ``README.rst``.\n\n    * - ``codacy``\n      - .. code:: python\n\n            \"no\"\n      - Add a Codacy_ badge in ``README.rst``.\n\n        **Note:** After importing the project in Codacy, find the hexadecimal project ID from settings and replace it in badge URL\n\n    * - ``codeclimate``\n      - .. code:: python\n\n            \"no\"\n      - Add a CodeClimate_ badge in ``README.rst``.\n\n    * - ``sphinx_docs``\n      - .. code:: python\n\n            \"yes\"\n      - Have Sphinx documentation.\n\n    * - ``sphinx_theme``\n      - .. code:: python\n\n            \"sphinx-rtd-theme\"\n      - What Sphinx_ theme to use.\n\n        Suggested alternative: `sphinx-py3doc-enhanced-theme \u003chttps://pypi.org/project/sphinx_py3doc_enhanced_theme\u003e`__\n        for a responsive theme based on the Python 3 documentation.\n\n    * - ``sphinx_doctest``\n      - .. code:: python\n\n            \"no\"\n      - Set to ``\"yes\"`` if you want to enable doctesting in the `docs` environment. Works best with\n        ``test_matrix_separate_coverage == 'no'``.\n\n        Read more about `doctest support in Sphinx \u003chttp://www.sphinx-doc.org/en/stable/ext/doctest.html\u003e`_.\n\n    * - ``sphinx_docs_hosting``\n      - .. code:: python\n\n            \"repo_name.readthedocs.io\"\n      - Leave as default if your documentation will be hosted on readthedocs.\n        If your documentation will be hosted elsewhere (such as GitHub Pages or GitLab Pages),\n        enter the top-level URL.\n\n    * - ``pypi_badge``\n      - .. code:: python\n\n            \"yes\"\n      - By default, this will insert links to your project's page on PyPI.org.\n        Note that if your package is not (yet) on PyPI, this will cause tox -e docs to fail.\n        If you choose \"no\", then these links will not be created.\n\n    * - ``pypi_disable_upload``\n      - .. code:: python\n\n            \"no\"\n      - If you specifically want to be sure your package will never be\n        accidentally uploaded to PyPI, you can pick \"yes\".\n\nDeveloping the project\n``````````````````````\n\nTo run all the tests, just run::\n\n  tox\n\nTo see all the tox environments::\n\n  tox -l\n\nTo only build the docs::\n\n  tox -e docs\n\nTo build and verify that the built package is proper and other code QA checks::\n\n  tox -e check\n\nReleasing the project\n`````````````````````\nBefore releasing your package on PyPI you should have all the tox environments passing.\n\nVersion management\n''''''''''''''''''\n\nThis template provides a basic bumpversion_ configuration. It's as simple as running:\n\n* ``bumpversion patch`` to increase version from `1.0.0` to `1.0.1`.\n* ``bumpversion minor`` to increase version from `1.0.0` to `1.1.0`.\n* ``bumpversion major`` to increase version from `1.0.0` to `2.0.0`.\n\nYou should read `Semantic Versioning 2.0.0 \u003chttp://semver.org/\u003e`_ before bumping versions.\n\nBuilding and uploading\n''''''''''''''''''''''\n\nBefore building dists make sure you got a clean build area::\n\n    rm -rf build\n    rm -rf src/*.egg-info\n\nNote:\n\n    Dirty ``build`` or ``egg-info`` dirs can cause problems: missing or stale files in the resulting dist or\n    strange and confusing errors. Avoid having them around.\n\nThen you should check that you got no packaging issues::\n\n    tox -e check\n\nAnd then you can build the ``sdist``, and if possible, the ``bdist_wheel`` too::\n\n    python setup.py clean --all sdist bdist_wheel\n\nTo make a release of the project on PyPI, assuming you got some distributions in ``dist/``, the most simple usage is::\n\n    twine upload --skip-existing dist/*.whl dist/*.gz dist/*.zip\n\nIn ZSH you can use this to upload everything in ``dist/`` that ain't a linux-specific wheel (you may need ``setopt extended_glob``)::\n\n    twine upload --skip-existing dist/*.(whl|gz|zip)~dist/*linux*.whl\n\nFor making and uploading `manylinux1 \u003chttps://github.com/pypa/manylinux\u003e`_ wheels you can use this contraption::\n\n    docker run --rm -itv $(pwd):/code quay.io/pypa/manylinux1_x86_64 bash -c 'set -eux; cd code; rm -rf wheelhouse; for variant in /opt/python/*; do rm -rf dist build *.egg-info \u0026\u0026 $variant/bin/python setup.py clean --all bdist_wheel; auditwheel repair dist/*.whl; done; rm -rf dist build *.egg-info'\n    twine upload --skip-existing wheelhouse/*.whl\n    docker run --rm -itv $(pwd):/code quay.io/pypa/manylinux1_i686 bash -c 'set -eux; cd code; rm -rf wheelhouse; for variant in /opt/python/*; do rm -rf dist build *.egg-info \u0026\u0026 $variant/bin/python setup.py clean --all bdist_wheel; auditwheel repair dist/*.whl; done; rm -rf dist build *.egg-info'\n    twine upload --skip-existing wheelhouse/*.whl\n\nNote:\n\n    `twine \u003chttps://pypi.org/project/twine\u003e`_ is a tool that you can use to securely upload your releases to PyPI.\n    You can still use the old ``python setup.py register sdist bdist_wheel upload`` but it's not very secure - your PyPI\n    password will be sent over plaintext.\n\nChangelog\n---------\n\nSee `CHANGELOG.rst \u003chttps://github.com/ionelmc/cookiecutter-pylibrary/blob/master/CHANGELOG.rst\u003e`_.\n\nQuestions \u0026 answers\n-------------------\n\nThere's no Makefile?\n\n  Sorry, no ``Makefile`` yet. The Tox_ environments stand for whatever you'd have in a ``Makefile``.\n\nWhy does ``tox.ini`` have a ``passenv = *``?\n\n  Tox 2.0 changes the way it runs subprocesses - it no longer passes all the environment variables by default. This causes\n  all sorts of problems if you want to run/use any of these with Tox: SSH Agents, Browsers (for Selenium), Appengine SDK,\n  VC Compiler and so on.\n\n  `cookiecutter-pylibrary` errs on the side of convenience here. You can always remove ``passenv = *`` if you like\n  the strictness.\n\nWhy is the version stored in several files (``pkg/__init__.py``, ``setup.py``, ``docs/conf.py``)?\n\n  We cannot use a metadata/version file [#]_ because this template is to be used with both distributions of packages (dirs\n  with ``__init__.py``) and modules (simple ``.py`` files that go straight in ``site-packages``). There's no good place\n  for that extra file if you're distributing modules.\n\n  But this isn't so bad - bumpversion_ manages the version string quite\n  neatly.\n\n.. [#] Example, an ``__about__.py`` file.\n\nNot Exactly What You Want?\n--------------------------\n\nNo way, this is the best. :stuck_out_tongue_winking_eye:\n\n\nIf you have criticism or suggestions please open up an Issue or Pull Request.\n\n.. _Travis-CI: http://travis-ci.com/\n.. _Tox: https://tox.wiki/\n.. _Sphinx: http://sphinx-doc.org/\n.. _Coveralls: https://coveralls.io/\n.. _ReadTheDocs: https://readthedocs.org/\n.. _Setuptools: https://pypi.org/project/setuptools\n.. _Pytest: http://pytest.org/\n.. _AppVeyor: http://www.appveyor.com/\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _Nose: http://nose.readthedocs.org/\n.. _isort: https://pypi.org/project/isort\n.. _bumpversion: https://pypi.org/project/bump2version\n.. _bump2version: https://github.com/c4urself/bump2version\n.. _Codecov: http://codecov.io/\n.. _Scrutinizer: https://scrutinizer-ci.com/\n.. _Codacy: https://codacy.com/\n.. _CodeClimate: https://codeclimate.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionelmc%2Fcookiecutter-pylibrary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fionelmc%2Fcookiecutter-pylibrary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fionelmc%2Fcookiecutter-pylibrary/lists"}