Metadata-Version: 2.1
Name: cookiecutter-python
Version: 1.8.6
Summary: Yet another modern Python Package (pypi) with emphasis in CI/CD and automation.
Home-page: https://github.com/boromir674/cookiecutter-python-package
License: AGPL-3.0-only
Keywords: python package generator,python package template,cookiecutter,python package,automation
Author: Konstantinos Lampridis
Author-email: k.lampridis@hotmail.com
Maintainer: Konstantinos Lampridis
Maintainer-email: k.lampridis@hotmail.com
Requires-Python: >3.6,<3.13
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Software Distribution
Classifier: Typing :: Typed
Provides-Extra: docs
Provides-Extra: test
Provides-Extra: typing
Requires-Dist: attrs (>=21.4.0,<22.0.0)
Requires-Dist: click (>=8,<9)
Requires-Dist: cookiecutter (>=1.7.3,<2.0.0)
Requires-Dist: gitpython (>=3.1,<4.0)
Requires-Dist: mypy (==0.961) ; extra == "typing"
Requires-Dist: pytest (>=6.2.4) ; extra == "test" or extra == "typing"
Requires-Dist: pytest-click (>=1.1.0,<1.2.0) ; extra == "test" or extra == "typing"
Requires-Dist: pytest-cov (>=2.12) ; extra == "test"
Requires-Dist: pytest-explicit (>=1.0.1,<1.1.0) ; extra == "test"
Requires-Dist: pytest-object-getter (>=1.0.1,<2.0.0) ; extra == "test"
Requires-Dist: pytest-requests-futures (==0.9.0) ; extra == "test"
Requires-Dist: pytest-run-subprocess (==0.9.0) ; extra == "test"
Requires-Dist: pytest-xdist (>=1.34) ; extra == "test"
Requires-Dist: pyyaml (>=6.0,<7.0) ; extra == "test"
Requires-Dist: questionary (>=1.10.0,<2.0.0)
Requires-Dist: requests-futures (>=1.0.0,<2.0.0)
Requires-Dist: software-patterns (>=1.3.0,<2.0.0)
Requires-Dist: sphinx (>=4.0,<5.0) ; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints (>=1.10) ; extra == "docs"
Requires-Dist: sphinx-rtd-theme (==0.5.0) ; extra == "docs"
Requires-Dist: sphinxcontrib-spelling (>=7.3.3,<7.4.0) ; extra == "docs"
Requires-Dist: types-pyyaml (>=6.0.12.5,<7.0.0.0) ; extra == "typing"
Requires-Dist: types-requests (>=2.27.26,<2.28.0) ; extra == "typing"
Project-URL: Bug Tracker, https://github.com/boromir674/cookiecutter-python-package/issues
Project-URL: CI: Github Actions, https://github.com/boromir674/cookiecutter-python-package/actions
Project-URL: Changelog, https://github.com/boromir674/cookiecutter-python-package/blob/master/CHANGELOG.rst
Project-URL: Code of Conduct, https://github.com/boromir674/cookiecutter-python-package/blob/master/CONTRIBUTING.rst
Project-URL: Documentation, https://python-package-generator.readthedocs.io/
Project-URL: Repository, https://github.com/boromir674/cookiecutter-python-package
Project-URL: Source Code, https://github.com/boromir674/cookiecutter-python-package
Description-Content-Type: text/x-rst

========================
Python Package Generator
========================

| |build| |release_version| |wheel| |supported_versions|
| |docs| |coverage| |maintainability| |codacy| |tech-debt|
| |ossf| |black| |gh-lic| |commits_since_specific_tag_on_master| |commits_since_latest_github_release|

| Generate Python Project, with CI/CD Pipeline for PyPI and Docker builds for easy DevOps.
| **Documentation available at https://python-package-generator.readthedocs.io/.**

What's included?
================

* `Generator` **CLI** to scaffold a modern Python Project, with cross-platform support; **Linux**, **MacOS**, **Windows**
* Option for Python Package "variant", supporting `module`, `module+cli`, and `pytest-plugin`
* Template (source at `src/cookiecutter_python/`_) of over **24 files** (see `Quickstart`_), to generate Project featuring:
  
  * Fully featured **CI/CD Pipeline**, running on `Github Actions`_, defined in `.github/`
  * **Documentation Pages**, with `sphinx` or `mkdocs`, hosted on `readthedocs` server, located in `docs` dir
  * **Test Suite**, using `pytest`_, located in `tests` dir
  * **Pypi Deploy Command**, supporting upload to both `pypi.org`_ and `test.pypi.org`_ servers
  * **Type Check Command**, using `mypy`_
  * **Lint** *Check* and `Apply` commands, using `isort`_ and `black`_
  * **Build Command**, using the `build`_ python package


What to expect?
===============

You can to be up and running with a new Python Package, and run workflows on Github Actions, such as:

.. image is expected to mostly be rendered on github.com, pypi.org, readthedocs.io
   in any case we care for these pages. Adjust images props (ie width if needed)

.. image:: assets/ci-open-v1.png
   :alt: CI Pipeline, running on Github Actions, for a Biskotaki Python Package
   :align: center
   :width: 100%

Link: https://github.com/boromir674/biskotaki/actions/runs/4157571651

1. **CI Pipeline**, running on `Github Actions`_, defined in `.github/`

   a. **Job Matrix**, spanning different `platform`'s and `python version`'s

      1. Platforms: `ubuntu-latest`, `macos-latest`
      2. Python Interpreters: `3.6`, `3.7`, `3.8`, `3.9`, `3.10`
   b. **Parallel Job** execution, generated from the `matrix`, that runs the `Test Suite`
   c. **Artifact** store of **Source** and **Wheel** Distributions, factoring Platform and Python Version


Auto Generated Sample Package **Biskotaki**
-------------------------------------------

Check the **Biskotaki** *Python Package Project*, for a taste of the project structure and capabilities this Template can generate!

It it entirely generated using this **Python Package Template:**

| **Source Code** hosted on *Github* at https://github.com/boromir674/biskotaki
| **Python Package** hosted on *pypi.org* at https://pypi.org/project/biskotaki/
| **CI Pipeline** hosted on *Github Actions* at https://github.com/boromir674/biskotaki/actions


Quickstart
==========

To **install** the latest ``Generator`` in your environment, run:

.. code-block:: shell

    pip install cookiecutter-python

The ``generate-python`` CLI should become available in your environment.

Next, create a file, let's call it ``gen-config.yml``, with the following content:

.. code-block:: yaml

    default_context:
        project_name: Demo Generated Project
        project_type: module+cli
        full_name: John Doe
        email: john.doe@something.org
        github_username: john-doe
        project_short_description: 'Demo Generated Project Description'
        initialize_git_repo: no
        interpreters: {"supported-interpreters": ["3.8", "3.9", "3.10", "3.11"]}


To **generate** a Python Package Project, run:

.. code-block:: sh

    mkdir gen-demo-dir
    cd gen-demo-dir
    
    generate-python --config-file ../gen-config.yml --no-input


Now, you should have generated a new Project for a Python Package, based on the `Template`_!

The Project should be located in the newly created ``demo-generated-project`` directory.


To leverage all out-of-the-box development operations (ie scripts), install `tox`_:

.. code-block:: shell

    python3 -m pip install --user 'tox<4'

To verify tox available in your environment, run: ``tox --version``


Please, do a `cd` into the newly created directory, ie `cd <my-great-python-package>`.

To run the Test Suite, `cd` into the newly created Project folder, and run:

.. code-block:: shell

    tox -e dev

All Tests should pass, and you should see a `coverage` report!


To run Type Checking against the Source Code, run:

.. code-block:: shell

    tox -e type

All Type Checks should pass!


To setup a Git Repository, run:

.. code-block:: shell

    git init
    git add .
    git checkout -b main
    git commit -m "Initial commit"


To setup a Remote Repository, run for example:

.. code-block:: shell

    git remote add origin <remote-repository-url>
    git push -u origin main


To trigger the CI/CD Pipeline, run:

.. code-block:: shell

    git push

Navigate to your github.com/username/your-repo/actions page, to see the CI Pipeline running!

| Develop your package's **Source Code** (`business logic`) inside `src/my_great_python_package` dir :)
| Develop your package's **Test Suite** (ie `unit-tests`, `integration tests`) inside `tests` dir :-)

Read the Documentation's `Use Cases`_ section for more on how to leverage your generated Python Package features.


Next Steps
----------

To prepare for an Open Source Project Development Lifecycle, you should visit the following websites:

* PyPI, test.pypi.org, Dockerhub, and Read the Docs, for setting up Release and Documentation Pipelines
* github.com/your-account to configure Actions, through the web UI
* Codecov, Codacy, and Codeclimate, for setting up Automated Code Quality, with CI Pipelines
* https://www.bestpractices.dev/ for registering your Project for OpenSSF Best Practices Badge

**Happy Developing!**

License
=======

|gh-lic|

* `GNU Affero General Public License v3.0`_


Free/Libre and Open Source Software (FLOSS)
-------------------------------------------

|ossf|




.. URL LINKS

.. _Cookiecutter documentation: https://cookiecutter.readthedocs.io/en/stable/

.. _CI: https://github.com/boromir674/cookiecutter-python-package/actions

.. _tox: https://tox.wiki/en/latest/

.. _pytest: https://docs.pytest.org/en/7.1.x/

.. _build: https://github.com/pypa/build

.. _pypi.org: https://pypi.org/

.. _test.pypi.org: https://test.pypi.org/

.. _mypy: https://mypy.readthedocs.io/en/stable/

.. _Github Actions: https://github.com/boromir674/cookiecutter-python-package/actions

.. _src/cookiecutter_python/: https://github.com/boromir674/cookiecutter-python-package/tree/master/src/cookiecutter_python

.. _Template: https://github.com/boromir674/cookiecutter-python-package/tree/master/src/cookiecutter_python

.. _Use Cases: https://python-package-generator.readthedocs.io/en/master/contents/30_usage/index.html#new-python-package-use-cases

.. _GNU Affero General Public License v3.0: https://github.com/boromir674/cookiecutter-python-package/blob/master/LICENSE

.. _isort: https://pycqa.github.io/isort/

.. _black: https://black.readthedocs.io/en/stable/



.. BADGE ALIASES

.. Build Status
.. Github Actions: Test Workflow Status for specific branch <branch>

.. |build| image:: https://img.shields.io/github/actions/workflow/status/boromir674/cookiecutter-python-package/test.yaml?link=https%3A%2F%2Fgithub.com%2Fboromir674%2Fcookiecutter-python-package%2Factions%2Fworkflows%2Ftest.yaml%3Fquery%3Dbranch%253Amaster
   :alt: GitHub Workflow Status (with event)

.. build target https://github.com/boromir674/cookiecutter-python-package/actions/workflows/test.yaml?query=branch%3Amaster


.. Documentation

.. |docs| image:: https://img.shields.io/readthedocs/python-package-generator/master?logo=readthedocs&logoColor=lightblue
    :alt: Read the Docs (version)
    :target: https://python-package-generator.readthedocs.io/en/master/

.. Code Coverage

.. |coverage| image:: https://img.shields.io/codecov/c/github/boromir674/cookiecutter-python-package/master?logo=codecov
    :alt: Codecov
    :target: https://app.codecov.io/gh/boromir674/cookiecutter-python-package

.. PyPI

.. |release_version| image:: https://img.shields.io/pypi/v/cookiecutter_python
    :alt: Production Version
    :target: https://pypi.org/project/cookiecutter-python/

.. |wheel| image:: https://img.shields.io/pypi/wheel/cookiecutter-python?color=green&label=wheel
    :alt: PyPI - Wheel
    :target: https://pypi.org/project/cookiecutter-python

.. |supported_versions| image:: https://img.shields.io/pypi/pyversions/cookiecutter-python?color=blue&label=python&logo=python&logoColor=%23ccccff
    :alt: Supported Python versions
    :target: https://pypi.org/project/cookiecutter-python


.. Github Releases & Tags

.. |commits_since_specific_tag_on_master| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/v1.8.6/master?color=blue&logo=github
    :alt: GitHub commits since tagged version (branch)
    :target: https://github.com/boromir674/cookiecutter-python-package/compare/v1.8.6..master

.. |commits_since_latest_github_release| image:: https://img.shields.io/github/commits-since/boromir674/cookiecutter-python-package/latest?color=blue&logo=semver&sort=semver
    :alt: GitHub commits since latest release (by SemVer)


.. LICENSE (eg AGPL, MIT)
.. Github License

.. |gh-lic| image:: https://img.shields.io/github/license/boromir674/cookiecutter-python-package
    :alt: GitHub
    :target: https://github.com/boromir674/cookiecutter-python-package/blob/master/LICENSE


.. Free/Libre Open Source Software
.. Open Source Software Best Practices

.. |ossf| image:: https://bestpractices.coreinfrastructure.org/projects/5988/badge
    :alt: OpenSSF
    :target: https://bestpractices.coreinfrastructure.org/en/projects/5988


.. CODE QUALITY

.. Codacy
.. Code Quality, Style, Security

.. |codacy| image:: https://app.codacy.com/project/badge/Grade/5be4a55ff1d34b98b491dc05e030f2d7
    :alt: Codacy
    :target: https://app.codacy.com/gh/boromir674/cookiecutter-python-package/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=boromir674/cookiecutter-python-package&amp;utm_campaign=Badge_Grade


.. Code Climate CI
.. Code maintainability & Technical Debt

.. |maintainability| image:: https://api.codeclimate.com/v1/badges/1d347d7dfaa134fd944e/maintainability
   :alt: Maintainability
   :target: https://codeclimate.com/github/boromir674/cookiecutter-python-package/

.. |tech-debt| image:: https://img.shields.io/codeclimate/tech-debt/boromir674/cookiecutter-python-package
    :alt: Code Climate technical debt
    :target: https://codeclimate.com/github/boromir674/cookiecutter-python-package/


.. Code Style with Black

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :alt: Black
    :target: https://github.com/psf/black

