Metadata-Version: 2.4
Name: xcookie
Version: 0.5.0
Summary: The xcookie cookie-cutter Module
Author-email: Jon Crall <erotemic@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Erotemic/xcookie
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: ubelt>=1.3.6
Requires-Dist: toml>=0.10.2
Requires-Dist: kwconf>=0.11.0
Requires-Dist: rich>=12.3.0
Requires-Dist: git-python>=1.0.0
Requires-Dist: black>=22.1.0
Requires-Dist: ruff>=0.15.0
Requires-Dist: packaging>=21.3
Requires-Dist: pyproject-fmt>=2.21.1
Requires-Dist: ruamel.yaml<=0.17.32,>=0.17.22
Requires-Dist: PyYAML>=6.0.2; python_version < "4.0" and python_version >= "3.12"
Requires-Dist: PyYAML>=6.0; python_version < "3.12"
Requires-Dist: argcomplete>=1.0
Requires-Dist: sphinx>=5.0.1
Requires-Dist: sphinx-autobuild>=2021.3.14
Requires-Dist: sphinx_rtd_theme>=1.0.0
Requires-Dist: sphinxcontrib-napoleon>=0.7
Requires-Dist: sphinx-autoapi>=1.8.4
Requires-Dist: Pygments>=2.12.0
Requires-Dist: myst_parser>=0.18.0
Requires-Dist: sphinx-reredirects>=0.0.1
Requires-Dist: tabulate>=0.9.0
Requires-Dist: kwutil>=0.3.8
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.1; extra == "docs"
Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
Requires-Dist: sphinx_rtd_theme>=1.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-napoleon>=0.7; extra == "docs"
Requires-Dist: sphinx-autoapi>=1.8.4; extra == "docs"
Requires-Dist: Pygments>=2.9.0; extra == "docs"
Requires-Dist: myst_parser>=0.18.0; extra == "docs"
Requires-Dist: sphinx-reredirects>=0.0.1; extra == "docs"
Requires-Dist: docutils>=0.20.1; extra == "docs"
Provides-Extra: optional
Requires-Dist: python-gitlab>=3.0; extra == "optional"
Provides-Extra: tests
Requires-Dist: xdoctest>=1.1.6; extra == "tests"
Requires-Dist: pytest>=8.4.2; python_version >= "3.14.0" and extra == "tests"
Requires-Dist: pytest>=6.2.5; (python_version < "3.14.0" and python_version >= "3.10.0") and extra == "tests"
Requires-Dist: pytest-cov>=3.0.0; extra == "tests"
Requires-Dist: pytest_timeout>=2.3.1; (python_version < "4.0" and python_version >= "3.12") and extra == "tests"
Requires-Dist: pytest_timeout>=1.4.2; python_version < "3.12" and extra == "tests"
Requires-Dist: coverage>=7.10.0; (python_version < "4.0" and python_version >= "3.14") and extra == "tests"
Requires-Dist: coverage>=6.1.1; (python_version < "3.14" and python_version >= "3.10") and extra == "tests"
Dynamic: license-file

The xcookie Module
==================

|GithubActions| |ReadTheDocs| |Pypi| |Downloads| |Codecov|


The ``xcookie`` module. A helper for templating python projects.


+------------------+----------------------------------------------+
| Read the docs    | https://xcookie.readthedocs.io               |
+------------------+----------------------------------------------+
| Github           | https://github.com/Erotemic/xcookie          |
+------------------+----------------------------------------------+
| Pypi             | https://pypi.org/project/xcookie             |
+------------------+----------------------------------------------+

The goal is to be able to setup and update Python project structures with consistent
boilerplate for things like CI, ``setup.py``, and requirements.

It handles:

* Multiple version control remotes:

  + Github

  + Gitlab

* pure python packages

* python packages with scikit-build binary extensions

* rotating secrets

* CI scripts for github or gitlab where the general pattern is:

  + Lint the project

  + Build the pure python or binary wheels

  + Test the wheels in the supported environments (i.e. different operating systems / versions of Python)

  + Optionally sign the wheels with online GPG keys

  + Upload the wheels to test pypi or live pypi.

This is primarily driven by the needs of my projects and thus has some logic
that is specific to things I'm doing. However, these are all generally behind
checks for the "erotemic" tag. I am working on slowly making this into a proper
CLI that is externally usable.


The top level CLI is command-oriented:


.. code::

    usage: xcookie [-h] [--version] {generate,bump,refresh-docs,rotate-secrets} ...

    commands:
      {generate,bump,refresh-docs,rotate-secrets}
        generate            generate or update project boilerplate
        bump                bump the package version and changelog
        refresh-docs        regenerate Sphinx API documentation
        rotate-secrets      rotate CI secrets for an existing repository

Run ``xcookie generate --help`` for the project-generation options.

Version bumps are a separate maintenance command. They update the authoritative
package version and roll ``CHANGELOG.md`` from the current release into the next
``Unreleased`` section::

    xcookie bump              # patch, by default
    xcookie bump patch
    xcookie bump minor
    xcookie bump major
    xcookie bump 2.0.0        # explicit target version


Invocations to create a new github repo:

.. code:: bash

    # Create a new python repo
    xcookie generate --repo_name=cookiecutter_purepy --repodir=$HOME/code/cookiecutter_purepy --tags="github,purepy"

    # Create a new binary repo
    xcookie generate --repo_name=cookiecutter_binpy --repodir=$HOME/code/cookiecutter_binpy --tags="github,binpy,gdal"


Given an initialized repository the general usage pattern is to edit the
generated ``pyproject.toml`` and modify values in the ``[tool.xcookie]``
section and then rerun ``xcookie generate`` in that directory. It will then
present you
with a diff of the proposed changes that you can reject, accept entirely, or
accept selectively.

For some files where the user is likely to do custom work, xcookie won't try to
overwrite the file unless you tell it to regenerate it.  The ``setup.py`` is
the main example of this, so if you want xcookie to update your setup.py you
would run ``xcookie generate --regen setup.py``

Documentation refresh is also a separate maintenance command:

.. code:: bash

    xcookie refresh-docs

Secret rotation is a separate maintenance command rather than a generation
option:

.. code:: bash

    xcookie rotate-secrets

The command loads the repository's xcookie configuration, prints the commands
it plans to run, and asks for confirmation before executing them.

.. |CircleCI| image:: https://circleci.com/gh/Erotemic/xcookie.svg?style=svg
    :target: https://circleci.com/gh/Erotemic/xcookie

.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/github/Erotemic/xcookie?branch=main&svg=True
   :target: https://ci.appveyor.com/project/Erotemic/xcookie/branch/main

.. |Codecov| image:: https://codecov.io/github/Erotemic/xcookie/badge.svg?branch=main&service=github
   :target: https://codecov.io/github/Erotemic/xcookie?branch=main

.. |Pypi| image:: https://img.shields.io/pypi/v/xcookie.svg
   :target: https://pypi.python.org/pypi/xcookie

.. |Downloads| image:: https://img.shields.io/pypi/dm/xcookie.svg
   :target: https://pypistats.org/packages/xcookie

.. |ReadTheDocs| image:: https://readthedocs.org/projects/xcookie/badge/?version=latest
    :target: http://xcookie.readthedocs.io/en/latest/

.. |CodeQuality| image:: https://api.codacy.com/project/badge/Grade/4d815305fc014202ba7dea09c4676343
    :target: https://www.codacy.com/manual/Erotemic/xcookie?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=Erotemic/xcookie&amp;utm_campaign=Badge_Grade

.. |GithubActions| image:: https://github.com/Erotemic/xcookie/actions/workflows/tests.yml/badge.svg?branch=main
    :target: https://github.com/Erotemic/xcookie/actions?query=branch%3Amain
