| Name | vspect JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Simple and lightweight command-line utility for working with Python package version strings. |
| upload_time | 2025-02-12 04:40:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2025 Jay Qi
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. |
| keywords |
cli
packaging
pep 440
versions
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# vspect
[](https://pypi.org/project/vspect/)
[](https://github.com/drivendataorg/vspect/actions?query=workflow%3Atests+branch%3Amain)
[](https://codecov.io/gh/drivendataorg/vspect)
**vspect** (**v**ersion in**spect**) is a simple and lightweight command-line utility for working with Python package version strings. It was created to make it easier to read and format version strings when doing automated package releases in CI.
There are two main parts to using vspect:
1. **Get a version string** by using one of three approaches:
- Use the **`package`** command with a package name, and vspect will look up that package's version in the current virtual environment.
- Use the **`read`** command to read a statically-defined version from a `pyproject.toml` file. Give it either the file path or its parent directory path.
- Use the **`parse`** command to with a version string you provide directly.
2. **Render it according to a specified format** by optionally providing a Python formatting string. If not specified, the full version will be printed.
Here are some examples:
```sh
# Look up a package's version
vspect package pip
#> 25.0.1
# Provide a format string to customize the format
vspect package pip "{major_minor_version}"
#> 25.0
# Read from pyproject.toml. Can either be direct path or its parent directory
vspect read . "{major_minor_version}"
#> 0.1
# Parse a directly given version string
vspect parse 1.2.3.post4.dev5 "v{major}.{minor}.{patch}{post}"
#> v1.2.3post4
```
See the ["Format string"](#format-string) section for all available replacement fields.
While it's primarily intended for use with Python packages, you can easily use the `parse` command to manipulate generic dotted version strings in any context.
vspect is lightweight with minimal dependencies. It only depends on the [packaging](https://packaging.pypa.io/en/stable/) package published by the [Python Packaging Authority (PyPA)](https://www.pypa.io/en/latest/) and a [backport](https://github.com/hukkin/tomli) of the standard library's tomllib for older versions of Python.
## Installation
vspect is available from [PyPI](https://pypi.org/project/vspect/):
```sh
pip install vspect
```
## Basic usage
```sh
vspect package PACKAGE_NAME [FORMAT_STRING]
# or
vspect read FILE_OR_DIR_PATH [FORMAT_STRING]
# or
vspect parse VERSION [FORMAT_STRING]
```
The `package` subcommand requires that vspect is installed in the same virtual environment as the package you are trying to look up.
## Format string
Both the `package` and `parse` subcommands take an optional `FORMAT_STRING`. The format string is just a regular Python format string that gets passed to `str.format()`. See ["Format String Syntax"](https://docs.python.org/3/library/string.html#formatstrings) in Python's documentation for additional help. The following replacement field names are passed in:
| Replacement field | Description | Example |
|-------------------------|-----------------------------------------------------------------|---------------------------------|
| `version` | The full version string. | `1.2.3.post4.dev5` |
| `base_version` | Excludes dev, pre, post, and local. | `1.2.3.post4.dev5` → `1.2.3` |
| `major_minor_version` | The major and minor version string only. | `1.2.3` → `1.2` |
| `public_version` | Excludes local. | `9!1.2.3.post4+local` → `9!1.2.3.post4` |
| `release_version` | Excludes epoch, dev, pre, post, and local. | `9!1.2.3.post4` → `1.2.3` |
| `major` | The major version number. | `1.2.3` → `1` |
| `minor` | The minor version number. | `1.2.3` → `2` |
| `micro` | The micro version number. | `1.2.3` → `3` |
| `patch` | Alias for `micro`. | `1.2.3` → `3` |
| `epoch` | The epoch string including the `!`. Empty if epoch is `0`. | `1!2.3` → `1!` |
| `epoch_number` | The epoch number. | `1!2.3` → `1` |
| `pre` | The pre-release string. Empty if none. | `1.2.3a4` → `a4` |
| `post` | The post-release string including `.post`. Empty if none. | `1.2.3.post4` → `.post4` |
| `post_number` | The post-release number. Empty if none. | `1.2.3.post4` → `4` |
| `dev` | The dev-release string including `.dev`. Empty if none. | `1.2.3.dev5` → `.dev5` |
| `dev_number` | The dev-release number. Empty if none. | `1.2.3.dev5` → `5` |
| `local` | The local version string including `+`. Empty if none. | `1.2.3+local` → `+local` |
| `local_segment` | The local version segment. Empty if none. | `1.2.3+local` → `local` |
Raw data
{
"_id": null,
"home_page": null,
"name": "vspect",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cli, packaging, pep 440, versions",
"author": null,
"author_email": "Jay Qi <jayqi@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/3a/eb/f8bde53d0f61f427120cea0748e2f8d1c207c154d1225741598db5ec2bc6/vspect-0.1.0.tar.gz",
"platform": null,
"description": "# vspect\n\n[](https://pypi.org/project/vspect/)\n[](https://github.com/drivendataorg/vspect/actions?query=workflow%3Atests+branch%3Amain)\n[](https://codecov.io/gh/drivendataorg/vspect)\n\n**vspect** (**v**ersion in**spect**) is a simple and lightweight command-line utility for working with Python package version strings. It was created to make it easier to read and format version strings when doing automated package releases in CI.\n\nThere are two main parts to using vspect:\n\n1. **Get a version string** by using one of three approaches:\n - Use the **`package`** command with a package name, and vspect will look up that package's version in the current virtual environment.\n - Use the **`read`** command to read a statically-defined version from a `pyproject.toml` file. Give it either the file path or its parent directory path.\n - Use the **`parse`** command to with a version string you provide directly.\n2. **Render it according to a specified format** by optionally providing a Python formatting string. If not specified, the full version will be printed.\n\nHere are some examples:\n\n```sh\n# Look up a package's version\nvspect package pip\n#> 25.0.1\n\n# Provide a format string to customize the format\nvspect package pip \"{major_minor_version}\"\n#> 25.0\n\n# Read from pyproject.toml. Can either be direct path or its parent directory\nvspect read . \"{major_minor_version}\"\n#> 0.1\n\n# Parse a directly given version string\nvspect parse 1.2.3.post4.dev5 \"v{major}.{minor}.{patch}{post}\"\n#> v1.2.3post4\n```\n\nSee the [\"Format string\"](#format-string) section for all available replacement fields.\n\nWhile it's primarily intended for use with Python packages, you can easily use the `parse` command to manipulate generic dotted version strings in any context.\n\nvspect is lightweight with minimal dependencies. It only depends on the [packaging](https://packaging.pypa.io/en/stable/) package published by the [Python Packaging Authority (PyPA)](https://www.pypa.io/en/latest/) and a [backport](https://github.com/hukkin/tomli) of the standard library's tomllib for older versions of Python.\n\n## Installation\n\nvspect is available from [PyPI](https://pypi.org/project/vspect/):\n\n```sh\npip install vspect\n```\n\n## Basic usage\n\n```sh\nvspect package PACKAGE_NAME [FORMAT_STRING]\n# or\nvspect read FILE_OR_DIR_PATH [FORMAT_STRING]\n# or\nvspect parse VERSION [FORMAT_STRING]\n```\n\nThe `package` subcommand requires that vspect is installed in the same virtual environment as the package you are trying to look up.\n\n## Format string\n\nBoth the `package` and `parse` subcommands take an optional `FORMAT_STRING`. The format string is just a regular Python format string that gets passed to `str.format()`. See [\"Format String Syntax\"](https://docs.python.org/3/library/string.html#formatstrings) in Python's documentation for additional help. The following replacement field names are passed in:\n\n| Replacement field | Description | Example |\n|-------------------------|-----------------------------------------------------------------|---------------------------------|\n| `version` | The full version string. | `1.2.3.post4.dev5` |\n| `base_version` | Excludes dev, pre, post, and local. | `1.2.3.post4.dev5` \u2192 `1.2.3` |\n| `major_minor_version` | The major and minor version string only. | `1.2.3` \u2192 `1.2` |\n| `public_version` | Excludes local. | `9!1.2.3.post4+local` \u2192 `9!1.2.3.post4` |\n| `release_version` | Excludes epoch, dev, pre, post, and local. | `9!1.2.3.post4` \u2192 `1.2.3` |\n| `major` | The major version number. | `1.2.3` \u2192 `1` |\n| `minor` | The minor version number. | `1.2.3` \u2192 `2` |\n| `micro` | The micro version number. | `1.2.3` \u2192 `3` |\n| `patch` | Alias for `micro`. | `1.2.3` \u2192 `3` |\n| `epoch` | The epoch string including the `!`. Empty if epoch is `0`. | `1!2.3` \u2192 `1!` |\n| `epoch_number` | The epoch number. | `1!2.3` \u2192 `1` |\n| `pre` | The pre-release string. Empty if none. | `1.2.3a4` \u2192 `a4` |\n| `post` | The post-release string including `.post`. Empty if none. | `1.2.3.post4` \u2192 `.post4` |\n| `post_number` | The post-release number. Empty if none. | `1.2.3.post4` \u2192 `4` |\n| `dev` | The dev-release string including `.dev`. Empty if none. | `1.2.3.dev5` \u2192 `.dev5` |\n| `dev_number` | The dev-release number. Empty if none. | `1.2.3.dev5` \u2192 `5` |\n| `local` | The local version string including `+`. Empty if none. | `1.2.3+local` \u2192 `+local` |\n| `local_segment` | The local version segment. Empty if none. | `1.2.3+local` \u2192 `local` |\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 Jay Qi\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Simple and lightweight command-line utility for working with Python package version strings.",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [
"cli",
" packaging",
" pep 440",
" versions"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e512e585733ed53769a67cc5ec56a76888cd2f47957782b162e70a75a70d8311",
"md5": "e181ef36d04f0408f661223d4f3e76ef",
"sha256": "5b99f08ca505ed35a35ddbebb949ab409a4048c50eb99e7e7dd5f085b5d05f83"
},
"downloads": -1,
"filename": "vspect-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e181ef36d04f0408f661223d4f3e76ef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7620,
"upload_time": "2025-02-12T04:40:49",
"upload_time_iso_8601": "2025-02-12T04:40:49.327478Z",
"url": "https://files.pythonhosted.org/packages/e5/12/e585733ed53769a67cc5ec56a76888cd2f47957782b162e70a75a70d8311/vspect-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3aebf8bde53d0f61f427120cea0748e2f8d1c207c154d1225741598db5ec2bc6",
"md5": "12ba09e00c99da76e9ef4b35026e93ac",
"sha256": "0ad0883f7340c8f792c84327801817c42c931f3fa06026d7b01dd2b7011926e5"
},
"downloads": -1,
"filename": "vspect-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "12ba09e00c99da76e9ef4b35026e93ac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 10928,
"upload_time": "2025-02-12T04:40:50",
"upload_time_iso_8601": "2025-02-12T04:40:50.642029Z",
"url": "https://files.pythonhosted.org/packages/3a/eb/f8bde53d0f61f427120cea0748e2f8d1c207c154d1225741598db5ec2bc6/vspect-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 04:40:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "vspect"
}
