Metadata-Version: 2.4
Name: extract_version
Version: 1.2.0
Summary: Python module for extracting version from the string or directory name
Author-email: Yurii Cherkasov <strategarius@protonmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/yuchdev/ExtractVersion
Project-URL: Bug Tracker, https://github.com/yuchdev/ExtractVersion/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

## Extract Version

![license](https://img.shields.io/github/license/yuchdev/ExtractVersion)
![workflow](https://github.com/yuchdev/ExtractVersion/actions/workflows/python-app.yml/badge.svg)
![issues](https://img.shields.io/github/issues/yuchdev/ExtractVersion)

Python module for extracting version from the string or directory name.
Could make use for creating an inventory of installed versions of a particular application 
or finding the latest installed version.

The module offers the following functionality:
* Fetching version string from the string or name of the directory
* Validating version string
* Sorting config and application directories that contain versions in its name

### Installation

The package can be installed from pip
```
pip install extract-version
```

There are archives of previous releases available on 
[Github](https://github.com/yuchdev/ExtractVersion/releases) 
with the mirror on [AWS](https://packages-s3-useast1-any.s3.dualstack.us-east-1.amazonaws.com/extract-version/extract_version-1.2.0-py3-none-any.whl)

### Examples:

1. We fetch version `2020.1.0` from string `PyCharm-2020.1.0`, or version `1.0` from `my_program_v1.0`

* `AppVersion.Major.Minor` version format

```python
extract_version(version_string="PyCharm-2020.1.0")
> "2020.1.0"
```
* `Major.Minor` version format

```python
extract_version(version_string="my_program_v1.0")
> "1.0"
```

2. Sort directories by the version of application

```python
sort_versions(["PyCharm-2018.1.2", "PyCharm-2018.2.0", "PyCharm-2020.1.0"])
> ["PyCharm-2018.1.2", "PyCharm-2018.2.0", "PyCharm-2020.1.0"]
```

3. In edge cases with more than one pattern present, e.g. `PyCharm-2018.1.2-windows-10.0`, 
we should provide a clue where the version should be extracted from, 
in a form of a pattern-regex, e.g.`PyCharm-(.*)-windows-10.0`
The call of such function may look like this:

```python
extract_version(version_string='PyCharm-2018.1.2-windows-10.0', pattern='PyCharm-(.*)-windows-10.0')
> "2018.1.2"
```

4. Create an inventory of installed versions of a particular application
```python
application_path = "C:/Users/user/AppData/Local/JetBrains/PyCharm"
pycharm_versions = available_versions(versions_path=application_path)
> {"2018.1.2": "PyCharm-2018.1.2", "2018.2.0": "PyCharm-2018.2.0", "2020.1.0": "PyCharm-2020.1.0"}
```

### Command line

Installing the package also provides an `extract-version` command (equivalently, `python -m extract_version`)
exposing the same functionality from the shell. Every subcommand also reads its input from stdin when no
arguments are given, so it composes with tools like `ls`/`find`.

```
extract-version extract "PyCharm-2020.1.0"
> 2020.1.0

extract-version extract "PyCharm-2018.1.2-windows-10.0" --pattern "PyCharm-(.*)-windows-10.0"
> 2018.1.2

extract-version sort 2018.1.2 2018.2.0 2020.1.0
> 2018.1.2
> 2018.2.0
> 2020.1.0

ls "C:/Users/user/AppData/Local/JetBrains/PyCharm" | extract-version last-version --pattern "PyCharm-(.*)"
> PyCharm-2020.1.0

extract-version available --path "C:/Users/user/AppData/Local/JetBrains/PyCharm" --json
> {"2018.1.2": "PyCharm-2018.1.2", "2018.2.0": "PyCharm-2018.2.0", "2020.1.0": "PyCharm-2020.1.0"}
```

Run `extract-version --help` or `extract-version <subcommand> --help` for the full option list.

### Releasing

`release_package.py` builds and installs the wheel locally, and can optionally publish it via
`--upload-s3`, `--create-release` (GitHub), and `--publish-pypi`. Each of those needs its own
external tool and credentials, installed and configured beforehand:

| Flag              | Tool     | Credentials                                    |
|-------------------|----------|-------------------------------------------------|
| `--upload-s3`     | `aws`    | `aws configure` (or an `AWS_PROFILE`/instance role) |
| `--create-release`| `gh`     | `gh auth login`                                |
| `--publish-pypi`  | `twine`  | a PyPI API token in `~/.pypirc`                |

Run `python scripts/install_deps.py` to install `aws`, `gh`, and `twine` (cross-platform:
pip-installs `awscli`/`twine` everywhere, and uses Homebrew/winget/apt for `gh` where available).
It does not set up credentials — do that with the commands in the table above.

If a tool or its credentials aren't ready when `release_package.py` reaches that step, the step
reports itself unavailable and the run rolls back every step already completed (deletes the S3
object, the git tag, and/or the GitHub release, in that order) before exiting — see
`ReleaseStep`/`run_release_pipeline()` in `release_package.py`.
