# packse
Python packaging scenarios.
## Installation
Only a local installation is supported at this time:
```bash
poetry install
```
Once installed, the `packse` command-line interface will be available.
Depending on your Poetry configuration, you may need to use `poetry run packse` instead or activate Poetry's
virtual environment.
## Usage
### Scenarios
A scenario is a JSON description of a dependency tree.
See [`scenarios/example.json`](./scenarios/example.json)
Each scenario file can contain one or more scenarios.
### Listing scenarios
A list of available scenarios can be printed with the `list` command:
```bash
packse list
```
By default, packse will search for scenarios in the current tree. You may also pass a file to read
from:
```bash
packse list scenarios/example.json
```
Each scenario will be listed with its unique identifier e.g. `example-cd797223`. This is the name of the package
that can be installed to run the scenario once it is built and published.
Each `packse` command supports reading multiple scenario files. For example, with `list`:
```bash
packse list scenarios/example.json scenarios/requires-does-not-exist.json
```
### Viewing scenarios
The dependency tree of a scenario can be previewed using the `view` command:
```
$ packse view scenarios/example.json
example-89cac9f1
├── root
│ └── requires a
│ └── satisfied by a-1.0.0
├── a
│ └── a-1.0.0
│ └── requires b>1.0.0
│ ├── satisfied by b-2.0.0
│ └── satisfied by b-3.0.0
└── b
├── b-1.0.0
├── b-2.0.0
│ └── requires c
│ └── unsatisfied: no versions for package
└── b-3.0.0
```
Note the `view` command will view all scenarios in a file by default. A single scenario can be viewed by providing
the `--name` option:
```
$ packse view scenarios/example.json --name example
example
This is an example scenario, in which the user depends on a single package `a` which requires `b`
example-89cac9f1
├── root
│ └── requires a
│ └── satisfied by a-1.0.0
├── a
│ └── a-1.0.0
│ └── requires b>1.0.0
│ ├── satisfied by b-2.0.0
│ └── satisfied by b-3.0.0
└── b
├── b-1.0.0
├── b-2.0.0
│ └── requires c
│ └── unsatisfied: no versions for package
└── b-3.0.0
```
Notice, when a specific scenario is specified, there is more information displayed.
### Building scenarios
A scenario can be used to generate packages and build distributions:
```bash
packse build scenario/example.json
```
The `build/` directory will contain sources for all of the packages in the scenario.
The `dist/` directory will contain built distributions for all of the packages in the scenario.
When a scenario is built, it is given a unique identifier based on a hash of the scenario contents and the project
templates used to generate the packages. Each package and requirement in the scenario will be prefixed with the
identifier. The unique identifier can be excluded using the `--no-hash` argument, however, this will prevent
publishing multiple times to a registry that does not allow overwrites.
The `PACKSE_VERSION_SEED` environment variable can be used to override the seed used to generate the unique
identifier, allowing versions to differ based on information outside of packse.
### Publishing scenarios
Built scenarios can be published to a Python Package Index with the `publish` command:
```bash
packse publish dist/example-cd797223
```
By default, packages are published to the Test PyPI server.
Credentials must be provided via the `PACKSE_PYPI_PASSWORD` environment variable. `PACKSE_PYPI_USERNAME` can be
used to set a username if not using an API token. If using a server which does not require authentication, the
`--anonymous` flag can be passed.
### Running a package index
_Requires installation with the `index` extra_
A local package index can be controlled with the `index` command. For example, to start a local package index:
```bash
packse index up
```
The `--bg` flag can be passed to run the index in the background.
When running an index in the background, state will be stored in the `~/.packse` directory. The `PACKSE_STATE_PATH`
environment variable can be used to change the state path.
Packages can be installed by passing the `--index-url` flag to the installer e.g. with `pip`:
```bash
pip install --index-url http://127.0.0.1:3141 example-0611cb74
```
Packages can be published to the index by providing the `--index-url` and `--anonymous` flags to the `publish` command:
```bash
packse publish dist/example-cd797223 --index-url http://localhost:3141 --anonymous
```
Packages can also be published to the index by placing their distributions in the configured `--dist-dir`. This defaults
to `./dist` which is also the default location used in `packse build`.
By default, the index will fallback to PyPI for missing packages. To test in isolation, use the `--offline` flag.
To stop an index running in the background use `packse index down`:
```
packse index down
```
### Serving scenarios
_Requires installation with the `serve` extra_
The `serve` command can be used to host, build, and publish scenarios in one step.
```bash
packse serve scenarios
```
Packse will watch for changes to the `scenarios` directory, and publish new versions on each change.
Note when developing, it is often useful to use the `--no-hash` flag to avoid having to determine the latest
hash for the scenario.
### Testing scenarios
Published scenarios can then be tested with your choice of package manager.
For example, with `pip`:
```bash
pip install -i https://test.pypi.org/simple/ example-cd797223
```
### Exporting scenarios
Scenario information can be exported with the `packse inspect`. This creates a JSON representation of the scenarios
with additional generated information such as the root package name and the tree displayed during `packse view`.
### Writing new scenarios
Scenario files may contain one or more scenarios written in JSON. See the existing scenarios for examples and
the `Scenario` type for details on the supported schema.
Raw data
{
"_id": null,
"home_page": null,
"name": "packse",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "uv, packse, requirements, packaging, testing",
"author": "Zanie",
"author_email": "contact@zanie.dev",
"download_url": "https://files.pythonhosted.org/packages/4d/17/d04b497094fbebeb1d2c960f44010b2e89a1383406c2541947bed8d6a8c4/packse-0.3.13.tar.gz",
"platform": null,
"description": "# packse\n\nPython packaging scenarios.\n\n## Installation\n\nOnly a local installation is supported at this time:\n\n```bash\npoetry install\n```\nOnce installed, the `packse` command-line interface will be available.\n\nDepending on your Poetry configuration, you may need to use `poetry run packse` instead or activate Poetry's\nvirtual environment.\n\n## Usage\n\n### Scenarios\n\nA scenario is a JSON description of a dependency tree.\n\nSee [`scenarios/example.json`](./scenarios/example.json)\n\nEach scenario file can contain one or more scenarios.\n\n### Listing scenarios\n\nA list of available scenarios can be printed with the `list` command:\n\n```bash\npackse list\n```\n\nBy default, packse will search for scenarios in the current tree. You may also pass a file to read\nfrom:\n\n```bash\npackse list scenarios/example.json\n```\n\nEach scenario will be listed with its unique identifier e.g. `example-cd797223`. This is the name of the package\nthat can be installed to run the scenario once it is built and published.\n\nEach `packse` command supports reading multiple scenario files. For example, with `list`:\n\n```bash\npackse list scenarios/example.json scenarios/requires-does-not-exist.json\n```\n\n### Viewing scenarios\n\nThe dependency tree of a scenario can be previewed using the `view` command:\n\n```\n$ packse view scenarios/example.json\nexample-89cac9f1\n\u251c\u2500\u2500 root\n\u2502 \u2514\u2500\u2500 requires a\n\u2502 \u2514\u2500\u2500 satisfied by a-1.0.0\n\u251c\u2500\u2500 a\n\u2502 \u2514\u2500\u2500 a-1.0.0\n\u2502 \u2514\u2500\u2500 requires b>1.0.0\n\u2502 \u251c\u2500\u2500 satisfied by b-2.0.0\n\u2502 \u2514\u2500\u2500 satisfied by b-3.0.0\n\u2514\u2500\u2500 b\n \u251c\u2500\u2500 b-1.0.0\n \u251c\u2500\u2500 b-2.0.0\n \u2502 \u2514\u2500\u2500 requires c\n \u2502 \u2514\u2500\u2500 unsatisfied: no versions for package\n \u2514\u2500\u2500 b-3.0.0\n```\n\nNote the `view` command will view all scenarios in a file by default. A single scenario can be viewed by providing\nthe `--name` option:\n\n```\n$ packse view scenarios/example.json --name example\nexample\n\nThis is an example scenario, in which the user depends on a single package `a` which requires `b`\n\nexample-89cac9f1\n\u251c\u2500\u2500 root\n\u2502 \u2514\u2500\u2500 requires a\n\u2502 \u2514\u2500\u2500 satisfied by a-1.0.0\n\u251c\u2500\u2500 a\n\u2502 \u2514\u2500\u2500 a-1.0.0\n\u2502 \u2514\u2500\u2500 requires b>1.0.0\n\u2502 \u251c\u2500\u2500 satisfied by b-2.0.0\n\u2502 \u2514\u2500\u2500 satisfied by b-3.0.0\n\u2514\u2500\u2500 b\n \u251c\u2500\u2500 b-1.0.0\n \u251c\u2500\u2500 b-2.0.0\n \u2502 \u2514\u2500\u2500 requires c\n \u2502 \u2514\u2500\u2500 unsatisfied: no versions for package\n \u2514\u2500\u2500 b-3.0.0\n```\n\nNotice, when a specific scenario is specified, there is more information displayed.\n\n### Building scenarios\n\nA scenario can be used to generate packages and build distributions:\n\n```bash\npackse build scenario/example.json\n```\n\nThe `build/` directory will contain sources for all of the packages in the scenario.\nThe `dist/` directory will contain built distributions for all of the packages in the scenario.\n\nWhen a scenario is built, it is given a unique identifier based on a hash of the scenario contents and the project\ntemplates used to generate the packages. Each package and requirement in the scenario will be prefixed with the\nidentifier. The unique identifier can be excluded using the `--no-hash` argument, however, this will prevent\npublishing multiple times to a registry that does not allow overwrites.\n\nThe `PACKSE_VERSION_SEED` environment variable can be used to override the seed used to generate the unique\nidentifier, allowing versions to differ based on information outside of packse.\n\n### Publishing scenarios\n\nBuilt scenarios can be published to a Python Package Index with the `publish` command:\n\n```bash\npackse publish dist/example-cd797223\n```\n\nBy default, packages are published to the Test PyPI server.\n\nCredentials must be provided via the `PACKSE_PYPI_PASSWORD` environment variable. `PACKSE_PYPI_USERNAME` can be\nused to set a username if not using an API token. If using a server which does not require authentication, the\n`--anonymous` flag can be passed.\n\n### Running a package index\n\n_Requires installation with the `index` extra_\n\nA local package index can be controlled with the `index` command. For example, to start a local package index:\n\n```bash\npackse index up\n```\n\nThe `--bg` flag can be passed to run the index in the background.\nWhen running an index in the background, state will be stored in the `~/.packse` directory. The `PACKSE_STATE_PATH`\nenvironment variable can be used to change the state path.\n\nPackages can be installed by passing the `--index-url` flag to the installer e.g. with `pip`:\n\n```bash\npip install --index-url http://127.0.0.1:3141 example-0611cb74\n```\n\nPackages can be published to the index by providing the `--index-url` and `--anonymous` flags to the `publish` command:\n\n```bash\npackse publish dist/example-cd797223 --index-url http://localhost:3141 --anonymous\n```\n\nPackages can also be published to the index by placing their distributions in the configured `--dist-dir`. This defaults\nto `./dist` which is also the default location used in `packse build`.\n\nBy default, the index will fallback to PyPI for missing packages. To test in isolation, use the `--offline` flag.\n\nTo stop an index running in the background use `packse index down`:\n```\npackse index down\n```\n\n### Serving scenarios\n\n_Requires installation with the `serve` extra_\n\nThe `serve` command can be used to host, build, and publish scenarios in one step.\n\n```bash\npackse serve scenarios\n```\n\nPackse will watch for changes to the `scenarios` directory, and publish new versions on each change.\n\nNote when developing, it is often useful to use the `--no-hash` flag to avoid having to determine the latest\nhash for the scenario.\n\n### Testing scenarios\n\nPublished scenarios can then be tested with your choice of package manager.\n\nFor example, with `pip`:\n\n```bash\npip install -i https://test.pypi.org/simple/ example-cd797223\n```\n\n### Exporting scenarios\n\nScenario information can be exported with the `packse inspect`. This creates a JSON representation of the scenarios\nwith additional generated information such as the root package name and the tree displayed during `packse view`.\n\n### Writing new scenarios\n\nScenario files may contain one or more scenarios written in JSON. See the existing scenarios for examples and\nthe `Scenario` type for details on the supported schema.\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.3.13",
"project_urls": null,
"split_keywords": [
"uv",
" packse",
" requirements",
" packaging",
" testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48b196ada6247c109609dc31ecb679119e5881ff19f92835cffa530cd0be27e1",
"md5": "1e82adae10d07e690c9af17537cc4672",
"sha256": "40b73d052c05d9b5089f6b5b3b95a30483c02e13248e4d5f712b1b2656ef9b34"
},
"downloads": -1,
"filename": "packse-0.3.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e82adae10d07e690c9af17537cc4672",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 30628,
"upload_time": "2024-04-10T13:48:32",
"upload_time_iso_8601": "2024-04-10T13:48:32.124737Z",
"url": "https://files.pythonhosted.org/packages/48/b1/96ada6247c109609dc31ecb679119e5881ff19f92835cffa530cd0be27e1/packse-0.3.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d17d04b497094fbebeb1d2c960f44010b2e89a1383406c2541947bed8d6a8c4",
"md5": "36eca1cd34fde5e795c98faba2083997",
"sha256": "03b44b3b62e47332ee930ed4bb84af0ebda1abacfa4003acfa522e7ba441a238"
},
"downloads": -1,
"filename": "packse-0.3.13.tar.gz",
"has_sig": false,
"md5_digest": "36eca1cd34fde5e795c98faba2083997",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 30002,
"upload_time": "2024-04-10T13:48:33",
"upload_time_iso_8601": "2024-04-10T13:48:33.831212Z",
"url": "https://files.pythonhosted.org/packages/4d/17/d04b497094fbebeb1d2c960f44010b2e89a1383406c2541947bed8d6a8c4/packse-0.3.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 13:48:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "packse"
}
JSON