diff --git a/README.md b/README.md index 7e74b99..87620e9 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,11 @@ uv tool install upgrade-dependencies You can then navigate to your project directory and execute: ``` -uvx upgrade-dependencies [OPTIONS] [COMMAND] +uvx upgrade-dependencies [OPTIONS] COMMAND [ARGS]... ``` +See the [CLI documentation](docs/usage.md) for information about how each command works. + ### Requirements All python requirements are installed by default. To successfully use the `update` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..430b2b3 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,133 @@ +# `upgrade-dependencies` + +**Usage**: + +```console +$ upgrade-dependencies [OPTIONS] COMMAND [ARGS]... +``` + +**Options**: + +* `--install-completion`: Install completion for the current shell. +* `--show-completion`: Show completion for the current shell, to copy it or customize the installation. +* `--help`: Show this message and exit. + +**Commands**: + +* `list-dependencies`: List all the dependencies for the project. +* `check-dependency`: Checks whether a dependency needs updating. +* `needs-updating`: Lists the dependencies that need updating. +* `latest-versions`: List the dependencies that aren't specified to the latest version. +* `update`: Updates a dependency to a specific (or latest) version. +* `format-yml`: Formats the workflow and pre-commit config yaml files. + +## `upgrade-dependencies list-dependencies` + +List all the dependencies for the project. + +**Usage**: + +```console +$ upgrade-dependencies list-dependencies [OPTIONS] +``` + +**Options**: + +* `--help`: Show this message and exit. + +## `upgrade-dependencies check-dependency` + +Checks whether a dependency needs updating. + +**Usage**: + +```console +$ upgrade-dependencies check-dependency [OPTIONS] DEPENDENCY +``` + +**Arguments**: + +* `DEPENDENCY`: Name of the dependency to check [required] + +**Options**: + +* `--help`: Show this message and exit. + +## `upgrade-dependencies needs-updating` + +Lists the dependencies that need updating. + +**Usage**: + +```console +$ upgrade-dependencies needs-updating [OPTIONS] +``` + +**Options**: + +* `--base / --no-base`: Include base dependencies [default: base] +* `--optional-deps / --no-optional-deps`: Include optional dependencies [default: optional-deps] +* `--group-deps / --no-group-deps`: Include dependency groups [default: group-deps] +* `--github-actions / --no-github-actions`: Include GitHub actions dependencies [default: github-actions] +* `--pre-commit / --no-pre-commit`: Include pre-commit dependencies [default: pre-commit] +* `--help`: Show this message and exit. + +## `upgrade-dependencies latest-versions` + +List the dependencies that aren't specified to the latest version. + +**Usage**: + +```console +$ upgrade-dependencies latest-versions [OPTIONS] +``` + +**Options**: + +* `--base / --no-base`: Include base dependencies [default: base] +* `--optional-deps / --no-optional-deps`: Include optional dependencies [default: optional-deps] +* `--group-deps / --no-group-deps`: Include dependency groups [default: group-deps] +* `--github-actions / --no-github-actions`: Include GitHub actions dependencies [default: no-github-actions] +* `--pre-commit / --no-pre-commit`: Include pre-commit dependencies [default: pre-commit] +* `--help`: Show this message and exit. + +## `upgrade-dependencies update` + +Updates a dependency to a specific (or latest) version. + +Makes changes to the dependency specification locally and creates a GitHub pull +request on a new branch (branch name = dependency/{package_name}-{version}). Make +sure this branch name does not exist locally or on GitHub. + +Requires git and the GitHub CLI to be installed. It is recommended to have a clean +git before running this command. + +**Usage**: + +```console +$ upgrade-dependencies update [OPTIONS] DEPENDENCY +``` + +**Arguments**: + +* `DEPENDENCY`: Dependency to update [required] + +**Options**: + +* `--version TEXT`: Version to update to, latest version if not specified +* `--target-branch TEXT`: Name of the branch to merge PR to [default: master] +* `--help`: Show this message and exit. + +## `upgrade-dependencies format-yml` + +Formats the workflow and pre-commit config yaml files. + +**Usage**: + +```console +$ upgrade-dependencies format-yml [OPTIONS] +``` + +**Options**: + +* `--help`: Show this message and exit. diff --git a/src/upgrade_dependencies/main.py b/src/upgrade_dependencies/main.py index 38342a8..2c7cb68 100644 --- a/src/upgrade_dependencies/main.py +++ b/src/upgrade_dependencies/main.py @@ -2,7 +2,7 @@ import asyncio import os -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Annotated import typer from packaging.version import Version @@ -25,7 +25,7 @@ @app.command() def list_dependencies(): - """Checks whether a dependency needs updating.""" + """List all the dependencies for the project.""" project = Project(gh_pat=GH_PAT) # base dependencies @@ -119,12 +119,10 @@ def list_dependencies(): @app.command() -def check_dependency(dependency: str): - """Checks whether a dependency needs updating. - - Args: - dependency: Name of the dependency to check. - """ +def check_dependency( + dependency: Annotated[str, typer.Argument(help="Name of the dependency to check")], +): + """Checks whether a dependency needs updating.""" project = Project(gh_pat=GH_PAT) try: @@ -156,24 +154,22 @@ def check_dependency(dependency: str): @app.command() def needs_updating( - base: bool = True, - optional_deps: bool = True, - group_deps: bool = True, - github_actions: bool = True, - pre_commit: bool = True, + base: Annotated[bool, typer.Option(help="Include base dependencies")] = True, + optional_deps: Annotated[ + bool, + typer.Option(help="Include optional dependencies"), + ] = True, + group_deps: Annotated[bool, typer.Option(help="Include dependency groups")] = True, + github_actions: Annotated[ + bool, + typer.Option(help="Include GitHub actions dependencies"), + ] = True, + pre_commit: Annotated[ + bool, + typer.Option(help="Include pre-commit dependencies"), + ] = True, ): - """List the dependencies that need updating. - - Args: - base: If set to True, includes the base dependencies. Defaults to True. - optional_deps: If set to True, includes the optional dependencies. Defaults to - True. - group_deps: If set to True, includes the dependency groups. Defaults to True. - github_actions: If set to True, includes the github actions dependencies. - Defaults to True. - pre_commit: If set to True, includes the pre-commit dependencies. Defaults to - True. - """ + """Lists the dependencies that need updating.""" # create project object project = Project(gh_pat=GH_PAT) @@ -225,24 +221,22 @@ def needs_updating( @app.command() def latest_versions( - base: bool = True, - optional_deps: bool = True, - group_deps: bool = True, - github_actions: bool = False, - pre_commit: bool = True, + base: Annotated[bool, typer.Option(help="Include base dependencies")] = True, + optional_deps: Annotated[ + bool, + typer.Option(help="Include optional dependencies"), + ] = True, + group_deps: Annotated[bool, typer.Option(help="Include dependency groups")] = True, + github_actions: Annotated[ + bool, + typer.Option(help="Include GitHub actions dependencies"), + ] = False, + pre_commit: Annotated[ + bool, + typer.Option(help="Include pre-commit dependencies"), + ] = True, ): - """List the dependencies that aren't pinned to the latest version. - - Args: - base: If set to True, includes the base dependencies. Defaults to True. - optional_deps: If set to True, includes the optional dependencies. Defaults to - True. - group_deps: If set to True, includes the dependency groups. Defaults to True. - github_actions: If set to True, includes the github actions dependencies. - Defaults to False. - pre_commit: If set to True, includes the pre-commit dependencies. Defaults to - True. - """ + """List the dependencies that aren't specified to the latest version.""" # create project object project = Project(gh_pat=GH_PAT) @@ -294,18 +288,24 @@ def latest_versions( @app.command() def update( - dependency: str, - version: str | None = None, - target_branch: str = "master", + dependency: Annotated[str, typer.Argument(help="Dependency to update")], + version: Annotated[ + str | None, + typer.Option(help="Version to update to, latest version if not specified"), + ] = None, + target_branch: Annotated[ + str, + typer.Option(help="Name of the branch to merge PR to"), + ] = "master", ): - """_summary_. + """Updates a dependency to a specific (or latest) version. - Make sure branch locally and on github do not already exist! + Makes changes to the dependency specification locally and creates a GitHub pull + request on a new branch (branch name = dependency/{package_name}-{version}). Make + sure this branch name does not exist locally or on GitHub. - Args: - dependency: _description_ - version: _description_ - target_branch: _description_ + Requires git and the GitHub CLI to be installed. It is recommended to have a clean + git before running this command. """ with Progress( SpinnerColumn(), diff --git a/todo.md b/todo.md index 2c41b85..183d876 100644 --- a/todo.md +++ b/todo.md @@ -11,7 +11,8 @@ - [x] Create changes to files - [x] Create pull request - [x] Add format yml files -- [ ] Documentation +- [x] Documentation +- [ ] Add release command - [ ] Handle uv better (not group) - [ ] Handle pre-commit yml extension (not yaml) - [ ] Add tests