# Poetry Plugin: Package Info

[![PyPi](https://img.shields.io/pypi/v/poetry-plugin-package-info.svg)](https://pypi.org/project/poetry-plugin-package-info/)
[![Stable Version](https://img.shields.io/pypi/v/poetry-plugin-package-info?label=stable)](https://pypi.org/project/poetry-plugin-package-info/)
[![Pre-release Version](https://img.shields.io/github/v/release/bellis/poetry-plugin-package-info?label=pre-release&include_prereleases&sort=semver)](https://pypi.org/project/poetry-plugin-package-info)
[![Python Versions](https://img.shields.io/pypi/pyversions/poetry-plugin-package-info)](https://pypi.org/project/poetry-plugin-package-info)
[![Code coverage Status](https://codecov.io/gh/bellis/poetry-plugin-package-info/branch/main/graph/badge.svg)](https://codecov.io/gh/bellis/poetry-plugin-package-info)
[![PyTest](https://github.com/bellis/poetry-plugin-package-info/workflows/test/badge.svg)](https://github.com/bellis/poetry-plugin-package-info/actions?query=workflow%3Atest)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/BEllis/poetry-plugin-package-info/main.svg)](https://results.pre-commit.ci/latest/github/BEllis/poetry-plugin-package-info/main)
[![Download Stats](https://img.shields.io/pypi/dm/poetry-plugin-package-info)](https://pypistats.org/packages/poetry-plugin-package-info)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

This package is a plugin that generates an `package_info.py` file with variables containing values from pyproject.toml and git.

## Installation

The easiest way to install the `package-info` plugin is via the `self add` command of Poetry.

```bash
poetry self add poetry-plugin-package-info
```

If you used `pipx` to install Poetry you can add the plugin via the `pipx inject` command.

```bash
pipx inject poetry poetry-plugin-package-info
```

Otherwise, if you used `pip` to install Poetry you can add the plugin packages via the `pip install` command.

```bash
pip install poetry-plugin-plugin-package-info
```

## Usage

By default, the `package-info.py` file is generated only when using the `generage-package-info` command in poetry,

```
poetry generate-package-info
```

The plugin can be enabled to run before `poetry build` command by adding the `run-before-build` to the project pyproject.toml file.

```toml
[tool.poetry-plugin-package-info]
run-before-build = true
```

The plugin can be re-configured in the pyproject.toml file, below are the options and their defaults.

```toml
[tool.poetry-plugin-package-info]

# Run before poetry build command
run-before-build = false

# The path relative to the pyproject.toml file
package-info-file-path = "package_name_in_snake_case/package_info.py"

# The line length to fit python code into.
line-length = 79

# The line separate to use.
line-separator = "\n"

# Any header code to put at the top of the file.
header = "# Auto-generated by poetry-plugin-package-info at {file-write-time}"

# Any foot code to put at the bottom of the file.
footer = ""

# Search parent directories (relative to pyproject.toml) for .git
git-search-parent-directories = false

# ordered list of variables to include in the file.
include = [
    "project-name",
    "project-description",
    "project-version",
    "project-homepage",
    "project-repository",
    "project-documentation",
    "project-classifiers",
    "project-authors",
    "project-license",
    "git-commit-id",
    "git-commit-author-name",
    "git-commit-author-email",
    "git-commit-timestamp",
    "git-branch-name",
    "git-branch-path",
    "git-has-staged-changes",
    "git-has-unstaged-changes",
    "git-has-changes"
]
```

Give the defaults, below is an example `package_info.py` file.

```python
# File was auto-generated by poetry-plugin-package-info at 2023-06-05T00:35:43Z
__project_name__ = "my-project"
__project_description__ = "Some description."
__project_version__ = "1.2.3"
__project_homepage__ = "https://python-poetry.org"
__project_repository__ = "https://github.com/python-poetry/poetry"
__project_documentation__ = "https://python-poetry.org/docs"
__project_classifiers__ = [
                              "Topic :: Software Development :: Build Tools",
                              "Topic :: Software Development :: Libraries :: Python Mo"
                              "dules",
                          ]
__project_authors__ = [
                          "Ben Ellis <ben.ellis@softweyr.co.uk>",
                      ]
__project_license__ = "MIT"
__git_commit_id__ = "c4192bc5524b6905de5bcbdc0840e932c48d90ff"
__git_commit_author_name__ = "Ben Ellis"
__git_commit_author_email__ = "ben.ellis@softweyr.co.uk"
__git_commit_timestamp__ = "2023-06-05T01:27:30+01:00"
__git_branch_name__ = "main"
__git_branch_path__ = "refs/heads/main"
__git_has_staged_changes__ = False
__git_has_unstaged_changes__ = False
__git_has_changes__ = False
```

## How-to

### Change variable names

```toml
[tool.poetry-plugin-package-info]

includes = [
    "project-name",
    "project-description",
    "git-commit-id",
    { "property" = "git-is-dirty", "variable_name" = "clean_me" }
]

```

## Related Projects

* [website](https://github.com/python-poetry/website): The official Poetry website and blog
* [poetry-plugin-export](https://github.com/python-poetry/poetry-plugin-export): Export Poetry projects/lock files to
foreign formats like requirements.txt (Used some test code from this project)
