Metadata-Version: 2.4
Name: dummy-versioning-demo
Version: 0.3.0
Summary: Dummy package for testing Python versioning and PyPI publishing
Author: Dummy Maintainer
License: MIT License
        
        Copyright (c) 2026 Neeraj Srivastava
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/neerajmythink/test-python-repo
Project-URL: Repository, https://github.com/neerajmythink/test-python-repo.git
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# test-python-repo

User guide for the demo package repository at
`https://github.com/neerajmythink/test-python-repo`.

This repository is used to test:
- Python package versioning from Git tags
- wheel and source distribution builds
- publishing to PyPI from GitHub Actions
- pulling the package from PyPI or Cloudsmith

## Overview

The repository name is `test-python-repo`, while the published Python package name is
`dummy-versioning-demo`.

The import name is `dummy_versioning_demo`.

Current package features:
- `hello()` returns a simple demo string
- `__version__` is generated automatically from Git metadata
- tests verify both the import and installed package version metadata

## Repository layout

- `pyproject.toml` - package metadata and build configuration
- `src/dummy_versioning_demo/` - package source code
- `tests/` - package tests
- `.github/workflows/ci.yml` - test matrix and build validation
- `.github/workflows/publish.yml` - publish to PyPI on GitHub release
- `build_package.sh` - create annotated release tag and build package artifacts
- `push_package.sh` - local upload helper using `twine`
- `pull_package.sh` - install helper for PyPI or Cloudsmith

## Requirements

- Python `3.9` or newer
- `pip`
- Git tags available locally when building release versions

For local build and release testing, install:
- `build`
- `pytest`
- `twine`

## Install for development

Create and activate a virtual environment, then install the package in editable mode.

Recommended flow:
- `pip install --upgrade pip`
- `pip install -e .`
- `pip install pytest build twine`

## Run the package locally

After installation, test the package in Python:
- `import dummy_versioning_demo`
- `dummy_versioning_demo.hello()`
- `dummy_versioning_demo.__version__`

## Run tests

Run the test suite with:
- `pytest -q`

The test suite verifies:
- the package imports correctly
- `hello()` returns the expected demo output
- installed package metadata matches `dummy_versioning_demo.__version__`

## Build distributions

Build both a wheel and source distribution with:
- `python -m build`

Or use the helper script to create an annotated release tag and build in one step:
- `./build_package.sh 0.1.0`
- `./build_package.sh 0.1.0 --push`

Artifacts are created in `dist/`:
- `*.whl`
- `*.tar.gz`

## Versioning

This repository uses `setuptools-scm`, so version numbers are generated automatically from Git tags.

You should not manually edit `src/dummy_versioning_demo/_version.py`.

Examples:
- Git tag `v0.1.0` -> package version `0.1.0`
- commits after that tag -> development versions such as `0.1.devN`

If your build currently shows `0.1.dev3`, it means the build was created from a commit that is not exactly on the `v0.1.0` tag.

To build version `0.1.0` exactly:
1. Commit your release-ready changes.
2. Create an annotated tag such as `v0.1.0` on that commit.
3. Push the tag to GitHub.
4. Rebuild the package.

You can automate steps 2 through 4 with:
- `./build_package.sh 0.1.0 --push`

Useful checks:
- `git tag`
- `git describe --tags --exact-match`
- `git ls-remote --tags origin`

## GitHub Actions

### CI workflow

`.github/workflows/ci.yml` runs on pushes to `main` and on pull requests.

It performs the following steps:
- tests on Python `3.9`, `3.10`, `3.11`, and `3.12`
- installs the package in editable mode
- runs `pytest`
- builds distribution artifacts

### Publish workflow

`.github/workflows/publish.yml` publishes to PyPI when a GitHub release is published.

It:
- checks out the repo with full tag history
- builds the package
- publishes using `pypa/gh-action-pypi-publish`

## Publish to PyPI

### Recommended: GitHub trusted publishing

This is the cleanest setup for this repo.

To enable it:
1. In PyPI, configure a Trusted Publisher for `neerajmythink/test-python-repo`.
2. In GitHub, keep or create the `pypi` environment.
3. Create a GitHub release from a version tag such as `v0.1.0`.

When the release is published, GitHub Actions builds and uploads the package to PyPI.

### Local publish with `twine`

The repo also includes `push_package.sh` for local uploads.

Before using it, export your PyPI token in the shell:
- `export TWINE_USERNAME=__token__`
- `export TWINE_PASSWORD=<your-pypi-token>`

Then run the helper script or upload directly with `twine`.

## Install from package indexes

The helper script `pull_package.sh` supports installing:
- from PyPI
- from Cloudsmith

It also supports these install modes:
- fixed version, currently `==0.1.0`
- latest version
- version range `>=0.1.0,<0.2.0`

For PyPI, equivalent examples are:
- `pip install 'dummy-versioning-demo==0.1.0'`
- `pip install 'dummy-versioning-demo'`
- `pip install 'dummy-versioning-demo>=0.1.0,<0.2.0'`

## Notes

- Keep `fetch-depth: 0` in CI and publish workflows so tag-based versioning works correctly.
- If there is no exact release tag on the current commit, `setuptools-scm` will generate a development version.
- The package name (`dummy-versioning-demo`) is different from the repository name (`test-python-repo`), which is normal but worth remembering during install and publish steps.
