Metadata-Version: 2.4
Name: cookiecutter-pypackage-gitlab
Version: 0.1.0
Summary: Cookiecutter template for a Python package in the GitLab ecosystem
Author-email: Scott Karlin <pypi@karlin-online.com>
License: MIT
Project-URL: homepage, https://gitlab.com/sck/cookiecutter-pypackage-gitlab
Project-URL: bugs, https://gitlab.com/sck/cookiecutter-pypackage-gitlab/issues
Project-URL: changelog, https://gitlab.com/sck/cookiecutter-pypackage-gitlab/blob/main/HISTORY.md
Project-URL: documentation, https://sck.gitlab.io/cookiecutter-pypackage-gitlab/
Keywords: cookiecutter,template,package,gitlab
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cookiecutter>=2.6.0
Dynamic: license-file

# Cookiecutter PyPackage GitLab

[Cookiecutter](https://github.com/cookiecutter/cookiecutter) template for a
Python package in the GitLab CI/CD ecosystem.

*   GitLab repo: https://gitlab.com/sck/cookiecutter-pypackage-gitlab/
*   Free software: MIT license

## Features

*   Dependency management with [uv](https://docs.astral.sh/uv/)
*   Task running with [make](https://www.gnu.org/software/make/)
*   Testing with [pytest](https://docs.pytest.org/) under GitLab CI
*   Auto-publish to package repository when you push a `v*` tag.
    (For [PyPI](https://pypi.org/) no API tokens are needed by using
    [Trusted Publishers](https://docs.pypi.org/trusted-publishers/).)
*   Hardened GitLab CI workflows: version-pinned Docker images
*   Documentation site built with [Zensical](https://zensical.org/) and
    auto-deployed to
    [GitLab Pages](https://docs.gitlab.com/user/project/pages/).
*   Linting with [ruff](https://docs.astral.sh/ruff/), type checking with
    [mypy](https://mypy.readthedocs.io) and [ty](https://docs.astral.sh/ty/)
*   Command line interface using
    [argparse](https://docs.python.org/3/library/argparse.html)

## Quickstart

Generate a new Python package by creating a temporary venv, installing the
package, and running the command.

```bash
python -m venv venv
source venv/bin/activate
pip install cookiecutter-pypackage-gitlab
cookiecutter-pypackage-gitlab
```

If you have [`uvx`](https://docs.astral.sh/uv/getting-started/installation/)
installed, you can also use it to run `cookiecutter-pypackage-gitlab` without
explicitly creating a temporary venv, installing the package, running the
package, and then removing the temporary venv:

```bash
uvx cookiecutter-pypackage-gitlab
```

You'll be prompted for some values:

```
[1/14] Project name for documentation (spaces allowed) (Python Boilerplate): My Package
[2/14] Project short description for pyproject.toml and docs (Python Boilerplate contains all the boilerplate you need to create a Python package in the GitLab ecosystem.): A short description of your package.
[3/14] Initial version string for the package (0.0.0):
[4/14] Author full name (Scott Karlin): Your Name
[5/14] Author email (scottkarlin@example.com): you@example.com
[6/14] Author GitLab username (sck): your-gitlab-username
[7/14] Author website (https://gitlab.com/your-gitlab-username):
[8/14] PyPI Package Name for pip install (no spaces; recommend normalized form) (my-package):
[9/14] GitLab repository URL for this project. (https://gitlab.com/your-gitlab-username/my-package):
[10/14] Display name of the project in GitLab (my-package):
[11/14] Python import package name (my_package):
[12/14] Target package registry: "pypi" to publish to PyPI or "gitlab" to publish to your GitLab project's package registry (gitlab):
[13/14] PyPI username (required when publish_registry is "pypi") ():
[14/14] The name of the local repo directory (my-package):
```

Then:

*   Create a GitLab repo and push your code
*   Enable GitLab Pages: Settings > Pages > Source: **GitLab CI**
*   Set up
    [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/)
    for your repo
*   Release your package: see
    [Release Checklist](docs/release_checklist.md) for the workflow.

See the **[full documentation](https://sck.gitlab.io/cookiecutter-pypackage-gitlab/)**
for the tutorial, CI/CD reference, design notes, and more.

## Development

To set up for local development:

```bash
git clone git@gitlab.com:sck/cookiecutter-pypackage-gitlab.git
cd cookiecutter-pypackage-gitlab
make venv
source venv/bin/activate
make init
make uv.lock
make sync-devci
```

Run quality checks (format, lint, type check, test):

```bash
make qa
```

Watch the template for changes and auto-regenerate `python-boilerplate/` in the
repo root (useful when iterating on template files):

```bash
make template-watch
```

### Release cycle

1. Edit code and add change notes to the `Next Release (TBD)` entry in
   `HISTORY.md` as you go.

2. When ready to release, upgrade all dependencies and refresh the environment:

    ```bash
    make update
    make sync-devci
    ```

3. Run the full quality check suite:

    ```bash
    make qa
    ```

4. In `HISTORY.md`, replace the `Next Release (TBD)` heading with the release
   version and today's date, and verify the change notes are complete.

5. Sync the version to `pyproject.toml` and `uv.lock`:

    ```bash
    make set-version
    ```

6. Commit the release:

    ```bash
    git commit -am "Release X.Y.Z"
    ```

7. Tag and push.  `make tag` validates version consistency across `HISTORY.md`,
   `pyproject.toml`, and `uv.lock`; creates an annotated tag; pushes it to
   `origin`; and adds a new `Next Release (TBD)` entry to `HISTORY.md`:

    ```bash
    make tag
    ```

    Pushing the tag triggers the GitLab CI/CD publish job, which uploads
    the package to your selected registry.

8. Commit to open the next development cycle:

    ```bash
    git commit -am "Start next development cycle"
    ```

9. Go back to step 1.

See also [Release Checklist](docs/release_checklist.md) for
registry-specific publishing notes and troubleshooting.

## Not Exactly What You Want?

Don't worry, you have options:

### Fork This / Create Your Own

If you have differences in your preferred setup, I encourage you to fork this
to create your own version.
Or create your own; it doesn't strictly have to be a fork.

### Similar Cookiecutter Templates

This cookiecutter template was based on the v0.4.0 (2026-02-16) release of
[Cookiecutter PyPackage](https://github.com/audreyfeldroy/cookiecutter-pypackage)
(a GitHub-centric template).
That package lists other forks you can explore to get ideas at
[network](https://github.com/audreyfeldroy/cookiecutter-pypackage/network)
and
[family tree](https://github.com/audreyfeldroy/cookiecutter-pypackage/network/members).

### Or Submit a Merge Request

I also accept merge requests on this, if they're small, atomic, follow my
design decisions, and if they make my own packaging experience better.
