harbor_cli.utils.commands

Attributes

PREFIX_ID = 'id:' module-attribute

OPTION_QUERY = typer.Option(None, '--query', help='Query parameters to filter the results.') module-attribute

OPTION_SORT = typer.Option(None, '--sort', help="Sorting order of the results. Example: [green]'name,-id'[/] to sort by name ascending and id descending.") module-attribute

OPTION_PAGE_SIZE = typer.Option(10, '--page-size', help='(Advanced) Results to fetch per API call.') module-attribute

OPTION_PAGE = typer.Option(1, '--page', help='(Advanced) Page to begin fetching from.') module-attribute

OPTION_LIMIT = typer.Option(None, '--limit', help='Maximum number of results to fetch.') module-attribute

OPTION_PROJECT_NAME_OR_ID = typer.Option(None, '--project', help=f'Project name or ID. {_USE_ID_HELP}') module-attribute

OPTION_FORCE = typer.Option(False, '--force', help='Force deletion without confirmation.') module-attribute

ARG_PROJECT_NAME = typer.Argument(None, help='Name of the project to use.') module-attribute

ARG_PROJECT_NAME_OR_ID = _arg_project_name_or_id() module-attribute

ARG_PROJECT_NAME_OR_ID_OPTIONAL = _arg_project_name_or_id(None) module-attribute

ARG_REPO_NAME = typer.Argument(..., help='Name of the repository to use.') module-attribute

ARG_USERNAME_OR_ID = typer.Argument(..., help=f'Username or ID of the user to use. {_USE_ID_HELP}') module-attribute

ARG_LDAP_GROUP_DN_OR_ID = typer.Argument(..., help=f'LDAP Group DN or ID of the group to use. {_USE_ID_HELP}') module-attribute

Classes

Functions

get_parent_ctx(ctx: typer.Context | click.core.Context) -> typer.Context | click.core.Context

Get the top-level parent context of a context.

Source code in harbor_cli/utils/commands.py

def get_parent_ctx(
    ctx: typer.Context | click.core.Context,
) -> typer.Context | click.core.Context:
    """Get the top-level parent context of a context."""
    if ctx.parent is None:
        return ctx
    return get_parent_ctx(ctx.parent)

get_command_help(command: typer.models.CommandInfo) -> str

Get the help text of a command.

Source code in harbor_cli/utils/commands.py

def get_command_help(command: typer.models.CommandInfo) -> str:
    """Get the help text of a command."""
    if command.help:
        return command.help
    if command.callback and command.callback.__doc__:
        lines = command.callback.__doc__.strip().splitlines()
        if lines:
            return lines[0]
    if command.short_help:
        return command.short_help
    return ""

get_app_commands(app: typer.Typer) -> list[CommandSummary] cached

Get a list of commands from a typer app.

Source code in harbor_cli/utils/commands.py

@lru_cache(maxsize=None)
def get_app_commands(app: typer.Typer) -> list[CommandSummary]:
    """Get a list of commands from a typer app."""
    return _get_app_commands(app)

get_app_callback_options(app: typer.Typer) -> list[typer.models.OptionInfo]

Get the options of the main callback of a Typer app.

Source code in harbor_cli/utils/commands.py

def get_app_callback_options(app: typer.Typer) -> list[typer.models.OptionInfo]:
    """Get the options of the main callback of a Typer app."""
    options = []  # type: list[typer.models.OptionInfo]

    if not app.registered_callback:
        return options

    callback = app.registered_callback.callback

    if not callback:
        return options
    if not hasattr(callback, "__defaults__") or not callback.__defaults__:
        return options

    for option in callback.__defaults__:
        options.append(option)
    return options

inject_help(model: Type[BaseModel], strict: bool = False, **field_additions: str) -> Any

Injects a Pydantic model's field descriptions into the help attributes of Typer.Option() function parameters whose names match the field names.

Examples:

class MyModel(BaseModel):
    my_field: str = Field(..., description="Description of my_field")

@app.command(name="my-command")
@inject_help(MyModel)
def my_command(my_field: str = typer.Option(...)):
    ...

# `my-app my-command --help`
# my_field's help text will be "Description of my_field"

NOTE

Does not modify the help text of options with existing help text! Use the **field_additions parameter to add additional help text to a field in addition to the field's description. This text is appended to the help text, separated by a space.

e.g. @inject_help(MyModel, my_field="Additional help text that is appended to the field's description.")

Parameters:

Name	Type	Description	Default
model	Type[BaseModel]	The pydantic model to use for help injection.	required
strict	bool	If True, fail if a field in the model does not correspond to a function parameter of the same name with a typer.OptionInfo as a default value.	False
**field_additions	str	Additional help text to add to the help attribute of a field. The parameter name should be the name of the field, and the value should be the additional help text to add. This is useful when the field's description is not sufficient, and you want to add additional help text to supplement the existing description.	{}

Source code in harbor_cli/utils/commands.py

def inject_help(
    model: Type[BaseModel], strict: bool = False, **field_additions: str
) -> Any:
    """
    Injects a Pydantic model's field descriptions into the help attributes
    of Typer.Option() function parameters whose names match the field names.

    Examples
    -------
    ```python
    class MyModel(BaseModel):
        my_field: str = Field(..., description="Description of my_field")

    @app.command(name="my-command")
    @inject_help(MyModel)
    def my_command(my_field: str = typer.Option(...)):
        ...

    # `my-app my-command --help`
    # my_field's help text will be "Description of my_field"
    ```

    NOTE
    ----
    Does not modify the help text of options with existing help text!
    Use the `**field_additions` parameter to add additional help text to a field
    in addition to the field's description. This text is appended to the
    help text, separated by a space.

    e.g. `@inject_help(MyModel, my_field="Additional help text that is appended to the field's description.")`

    Parameters
    ----------
    model : Type[BaseModel]
        The pydantic model to use for help injection.
    strict : bool
        If True, fail if a field in the model does not correspond to a function
        parameter of the same name with a typer.OptionInfo as a default value.
    **field_additions
        Additional help text to add to the help attribute of a field.
        The parameter name should be the name of the field, and the value
        should be the additional help text to add. This is useful when
        the field's description is not sufficient, and you want to add
        additional help text to supplement the existing description.
    """

    def decorator(func: Any) -> Any:
        sig = inspect.signature(func)
        for field_name, field in model.model_fields.items():
            # only overwrite help if not already set
            param = sig.parameters.get(field_name, None)
            if not param:
                if strict:
                    raise ValueError(
                        f"Field {field_name!r} not found in function signature of {func.__qualname__!r}."
                    )
                continue
            if not hasattr(param, "default") or not hasattr(param.default, "help"):
                continue
            if not param.default.help:
                addition = field_additions.get(field_name, "")
                if addition:
                    addition = f" {addition}"  # add leading space
                param.default.help = f"{field.description or ''}{addition}"
        return func

    return decorator

inject_resource_options(f: Any = None, *, strict: bool = False, use_defaults: bool = True) -> Any

Decorator that calls inject_query, inject_sort, inject_page_size, inject_page and inject_limit to inject typer.Option() defaults for common options used when querying multiple resources.

NOTE: needs to be specified BEFORE @app.command() in order to work!

Not strict by default, so that it can be used on functions that only have a subset of the parameters (e.g. only query and sort).

The decorated function should always declare the parameters in the following order if the parameters don't have defaults: query, sort, page, page_size, limit

Examples:

@app.command()
@inject_resource_options()
def my_command(query: str, sort: str, page: int, page_size: int, limit: Optional[int]):
    ...

# OK
@app.command()
@inject_resource_options()
def my_command(query: str, sort: str):
    ...

# NOT OK (missing all required parameters)
@app.command()
@inject_resource_options(strict=True)
def my_command(query: str, sort: str):
    ...

# OK (inherits defaults)
@app.command()
@inject_resource_options()
def my_command(query: str, sort: str, page: int = typer.Option(1)):
    ...

# NOT OK (syntax error [non-default param after param with default])
# Use ellipsis to specify unset defaults
@app.command()
@inject_resource_options()
def my_command(query: str = typer.Option("tag=latest"), sort: str, page: int):

# OK (inherit default query, but override others)
# Use ellipsis to specify unset defaults
@app.command()
@inject_resource_options()
def my_command(query: str = typer.Option("my-query"), sort: str = ..., page: int = ...):

Parameters:

Name	Type	Description	Default
f	Any	The function to decorate, by default None	None
strict	bool	If True, fail if function is missing any of the injected parameters, by default False E.g. all of query, sort, page, page_size, limit must be present	False
use_defaults	bool	If True, use the default value specified by a parameter's typer.Option() field as the default value for the parameter, by default True.	True

Returns:

Type	Description
Any	The decorated function

Examples:

@inject_resource_options(use_defaults=True)
my_func(page_size: int = typer.Option(20)) -> None: ...

If use_defaults is True, the default value of page_size will be 20, instead of 10, which is the value inject_page_size() would use by default.

Warning

inject_resource_options() only accepts parameter defaults specified with typer.Option() and typer.Argument()!

@inject_resource_options(use_default=True)
my_func(page_size: int = 20) -> None: ... # will fail (for now)

Source code in harbor_cli/utils/commands.py

def inject_resource_options(
    f: Any = None, *, strict: bool = False, use_defaults: bool = True
) -> Any:
    """Decorator that calls inject_query, inject_sort, inject_page_size,
    inject_page and inject_limit to inject typer.Option() defaults
    for common options used when querying multiple resources.

    NOTE: needs to be specified BEFORE @app.command() in order to work!

    Not strict by default, so that it can be used on functions that only
    have a subset of the parameters (e.g. only query and sort).

    The decorated function should always declare the parameters in the following order
    if the parameters don't have defaults:
    `query`, `sort`, `page`, `page_size`, `limit`

    Examples
    -------
    ```python
    @app.command()
    @inject_resource_options()
    def my_command(query: str, sort: str, page: int, page_size: int, limit: Optional[int]):
        ...

    # OK
    @app.command()
    @inject_resource_options()
    def my_command(query: str, sort: str):
        ...

    # NOT OK (missing all required parameters)
    @app.command()
    @inject_resource_options(strict=True)
    def my_command(query: str, sort: str):
        ...

    # OK (inherits defaults)
    @app.command()
    @inject_resource_options()
    def my_command(query: str, sort: str, page: int = typer.Option(1)):
        ...

    # NOT OK (syntax error [non-default param after param with default])
    # Use ellipsis to specify unset defaults
    @app.command()
    @inject_resource_options()
    def my_command(query: str = typer.Option("tag=latest"), sort: str, page: int):

    # OK (inherit default query, but override others)
    # Use ellipsis to specify unset defaults
    @app.command()
    @inject_resource_options()
    def my_command(query: str = typer.Option("my-query"), sort: str = ..., page: int = ...):
    ```

    Parameters
    ----------
    f : Any, optional
        The function to decorate, by default None
    strict : bool, optional
        If True, fail if function is missing any of the injected parameters, by default False
        E.g. all of `query`, `sort`, `page`, `page_size`, `limit` must be present
    use_defaults : bool, optional
        If True, use the default value specified by a parameter's typer.Option() field
        as the default value for the parameter, by default True.

    Returns
    -------
    Any
        The decorated function

    Examples
    -------
    ```python
    @inject_resource_options(use_defaults=True)
    my_func(page_size: int = typer.Option(20)) -> None: ...
    ```
    If use_defaults is True, the default value of page_size will be 20,
    instead of 10, which is the value inject_page_size() would use by default.
    !!! warning
        `inject_resource_options()` only accepts parameter defaults specified with typer.Option() and typer.Argument()!

    ```python
    @inject_resource_options(use_default=True)
    my_func(page_size: int = 20) -> None: ... # will fail (for now)
    ```
    """

    # TODO: add check that the function signature is in the correct order
    # so we don't raise a cryptic error message later on!

    def decorator(func: Any) -> Any:
        # Inject in reverse order, because parameters with defaults
        # can't be followed by parameters without defaults
        for inject in [
            inject_limit,
            inject_page_size,
            inject_page,
            inject_sort,
            inject_query,
        ]:
            func = inject(func, strict=strict, use_default=use_defaults)
        return func

    # Support using plain @inject_resource_options or @inject_resource_options()
    if callable(f):
        return decorator(f)
    else:
        return decorator

inject_query(f: Any = None, *, strict: bool = False, use_default: bool = True) -> Any

Source code in harbor_cli/utils/commands.py

def inject_query(
    f: Any = None, *, strict: bool = False, use_default: bool = True
) -> Any:
    def decorator(func: Any) -> Any:
        return _patch_param(func, "query", OPTION_QUERY, strict, use_default)

    # Support using plain @inject_query or @inject_query()
    if callable(f):
        return decorator(f)
    else:
        return decorator

inject_sort(f: Any = None, *, strict: bool = False, use_default: bool = True) -> Any

Source code in harbor_cli/utils/commands.py

def inject_sort(
    f: Any = None, *, strict: bool = False, use_default: bool = True
) -> Any:
    def decorator(func: Any) -> Any:
        return _patch_param(func, "sort", OPTION_SORT, strict, use_default)

    # Support using plain @inject_sort or @inject_sort()
    if callable(f):
        return decorator(f)
    else:
        return decorator

inject_page_size(f: Any = None, *, strict: bool = False, use_default: bool = True) -> Any

Source code in harbor_cli/utils/commands.py

def inject_page_size(
    f: Any = None, *, strict: bool = False, use_default: bool = True
) -> Any:
    def decorator(func: Any) -> Any:
        return _patch_param(func, "page_size", OPTION_PAGE_SIZE, strict, use_default)

    # Support using plain @inject_page_size or @inject_page_size()
    if callable(f):
        return decorator(f)
    else:
        return decorator

inject_page(f: Any = None, *, strict: bool = False, use_default: bool = True) -> Any

Source code in harbor_cli/utils/commands.py

def inject_page(
    f: Any = None, *, strict: bool = False, use_default: bool = True
) -> Any:
    def decorator(func: Any) -> Any:
        return _patch_param(func, "page", OPTION_PAGE, strict, use_default)

    # Support using plain @inject_page or @inject_page()
    if callable(f):
        return decorator(f)
    else:
        return decorator

inject_limit(f: Any = None, *, strict: bool = False, use_default: bool = False) -> Any

Source code in harbor_cli/utils/commands.py

def inject_limit(
    f: Any = None, *, strict: bool = False, use_default: bool = False
) -> Any:
    def decorator(func: Any) -> Any:
        return _patch_param(func, "limit", OPTION_LIMIT, strict, use_default)

    # Support using plain @inject_page or @inject_page()
    if callable(f):
        return decorator(f)
    else:
        return decorator

inject_project_name(f: Any = None, *, strict: bool = False, use_default: bool = True) -> Any

Source code in harbor_cli/utils/commands.py

def inject_project_name(
    f: Any = None, *, strict: bool = False, use_default: bool = True
) -> Any:
    def decorator(func: Any) -> Any:
        return _patch_param(func, "project_name", ARG_PROJECT_NAME, strict, use_default)

    # Support using plain @inject_query or @inject_query()
    if callable(f):
        return decorator(f)
    else:
        return decorator