openapi-spec-tools 0.1.0__tar.gz

openapi_spec_tools-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rick Porter
+
+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.

openapi_spec_tools-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.3
+Name: openapi-spec-tools
+Version: 0.1.0
+Summary: OpenAPI specification tools for analyzing, updating, and generating a CLI.
+Author: Rick Porter
+Author-email: rickwporter@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Requires-Dist: rich (>=13.9.4,<14.0.0)
+Requires-Dist: typer (>=0.15.1,<0.16.0)
+Description-Content-Type: text/markdown
+
+# oas-tools
+
+Welcome to OpenAPI specification (OAS) tools!
+
+This is a collection of tools for using OpenAPI specifications. The OpenAPI community has a plethora of tools, and this is intended to supplement those. The tools here provide functionality that has not been readily available elsewhere.
+
+## OAS
+
+The `oas` script provides a tool for analyzing and modifying an OpenAPI spec. See [OAS.md](OAS.md) for more info.
+
+## CLI Generation
+
+The `cli-gen` tool allows users to create a user-friendly CLI using the OpenAPI spec and a layout file. The layout file provides the CLI structure and refers to the OpenAPI spec for details of operations.  [LAYOUT.md](LAYOUT.md) has more details about the layout file, and the [CLI_GEN.md](CLI_GEN.md) has more info about CLI generation.
+
+See the examples in `examples/` for some more complete works.
+
+## client.mk
+
+The `client.mk` file is an example of a `Makefile` to invoke the [OpenAPI generator](https://github.com/OpenAPITools/openapi-generator) via a container. The file can be copied/modified to be invoked with an OpenAPI specfication (other than `openapi.yaml`) and a real package name. For a more complete list of generator options, look at the [OpenAPI generator usage documentation](https://openapi-generator.tech/docs/usage#generate).
+
+## Contributing
+
+The [DEVELOPMENT.md](DEVELOPMENT.md) has more information about getting setup as a developer.
+
+The [TODO.md](TODO.md) has some ideas where this project can be improved and expanded -- please add your ideas here, or email Rick directly (rickwporter@gmail.com). 
+

openapi_spec_tools-0.1.0/README.md

@@ -0,0 +1,25 @@
+# oas-tools
+
+Welcome to OpenAPI specification (OAS) tools!
+
+This is a collection of tools for using OpenAPI specifications. The OpenAPI community has a plethora of tools, and this is intended to supplement those. The tools here provide functionality that has not been readily available elsewhere.
+
+## OAS
+
+The `oas` script provides a tool for analyzing and modifying an OpenAPI spec. See [OAS.md](OAS.md) for more info.
+
+## CLI Generation
+
+The `cli-gen` tool allows users to create a user-friendly CLI using the OpenAPI spec and a layout file. The layout file provides the CLI structure and refers to the OpenAPI spec for details of operations.  [LAYOUT.md](LAYOUT.md) has more details about the layout file, and the [CLI_GEN.md](CLI_GEN.md) has more info about CLI generation.
+
+See the examples in `examples/` for some more complete works.
+
+## client.mk
+
+The `client.mk` file is an example of a `Makefile` to invoke the [OpenAPI generator](https://github.com/OpenAPITools/openapi-generator) via a container. The file can be copied/modified to be invoked with an OpenAPI specfication (other than `openapi.yaml`) and a real package name. For a more complete list of generator options, look at the [OpenAPI generator usage documentation](https://openapi-generator.tech/docs/usage#generate).
+
+## Contributing
+
+The [DEVELOPMENT.md](DEVELOPMENT.md) has more information about getting setup as a developer.
+
+The [TODO.md](TODO.md) has some ideas where this project can be improved and expanded -- please add your ideas here, or email Rick directly (rickwporter@gmail.com). 

openapi_spec_tools-0.1.0/openapi_spec_tools/__init__.py

@@ -0,0 +1,10 @@
+from openapi_spec_tools.utils import count_values
+from openapi_spec_tools.utils import find_diffs
+from openapi_spec_tools.utils import find_paths
+from openapi_spec_tools.utils import find_references
+from openapi_spec_tools.utils import map_operations
+from openapi_spec_tools.utils import open_oas
+from openapi_spec_tools.utils import remove_schema_tags
+from openapi_spec_tools.utils import schema_operations_filter
+from openapi_spec_tools.utils import set_nullable_not_required
+from openapi_spec_tools.utils import unroll

openapi_spec_tools-0.1.0/openapi_spec_tools/_typer.py

@@ -0,0 +1,18 @@
+"""
+This provides some common extensions to Typer.
+"""
+
+import typer
+from rich import print
+from typing_extensions import Annotated
+
+# Common argument definition
+OasFilenameArgument = Annotated[str, typer.Argument(show_default=False, help="OpenAPI specification file")]
+
+
+def error_out(message: str, exit_code: int = 1) -> None:
+    """Utility to print provided error message (with red ERROR prefix) and exit"""
+    print(f"[red]ERROR:[/red] {message}")
+    raise typer.Exit(exit_code)
+
+

openapi_spec_tools-0.1.0/openapi_spec_tools/cli_gen/_arguments.py

@@ -0,0 +1,101 @@
+from typing import Optional
+
+import typer
+from typing_extensions import Annotated
+
+from openapi_spec_tools.cli_gen._display import OutputFormat
+from openapi_spec_tools.cli_gen._display import OutputStyle
+from openapi_spec_tools.cli_gen._logging import LogLevel
+from openapi_spec_tools.cli_gen._tree import TreeDisplay
+
+ENV_API_HOST = "API_HOST"
+ENV_API_KEY = "API_KEY"
+ENV_API_TIME = "API_TIMEOUT"
+ENV_LOG_LEVEL = "LOG_LEVEL"
+ENV_OUT_FORMAT = "OUTPUT_FORMAT"
+ENV_OUT_STYLE = "OUTPUT_STYLE"
+
+ApiKeyOption = Annotated[
+    str,
+    typer.Option(
+        "--api-key",
+        show_default=False,
+        envvar=ENV_API_KEY,
+        help="API key for authentication",
+    ),
+]
+ApiHostOption = Annotated[
+    str,
+    typer.Option(
+        "--api-host",
+        show_default=False,
+        envvar=ENV_API_HOST,
+        help="API host address",
+    ),
+]
+ApiTimeoutOption = Annotated[
+    int,
+    typer.Option(
+        "--api-timeout",
+        envvar=ENV_API_TIME,
+        help="API request timeout in seconds for a single request",
+    ),
+]
+DetailsOption = Annotated[
+    bool,
+    typer.Option(
+        "--details/--summary",
+        "-v",
+        help="Display the full details or a summary."
+    ),
+]
+LogLevelOption = Annotated[
+    LogLevel,
+    typer.Option(
+        "--log",
+        case_sensitive=False,
+        envvar=ENV_LOG_LEVEL,
+        help="Log level",
+    ),
+]
+MaxDepthOption = Annotated[
+    int,
+    typer.Option(
+        "--depth",
+        "--max-depth",
+        help="Maximum depth of tree to display."
+    ),
+]
+MaxCountOption = Annotated[
+    Optional[int],
+    typer.Option(
+        "--max",
+        "--max-count",
+        help="Maximum number of items to get (if any)."
+    )
+]
+OutputFormatOption = Annotated[
+    OutputFormat,
+    typer.Option(
+        "--format",
+        case_sensitive=False,
+        envvar=ENV_OUT_FORMAT,
+        help="Output format style",
+    ),
+]
+OutputStyleOption = Annotated[
+    OutputStyle,
+    typer.Option(
+        "--style",
+        case_sensitive=False,
+        envvar=ENV_OUT_STYLE,
+        help="Style for output",
+    ),
+]
+TreeDisplayOption = Annotated[
+    TreeDisplay,
+    typer.Option(
+        case_sensitive=False,
+        help="Details of the CLI command tree to show."
+    ),
+]

openapi_spec_tools-0.1.0/openapi_spec_tools/cli_gen/_console.py

@@ -0,0 +1,25 @@
+import os
+
+from rich.console import Console
+
+TEST_TERMINAL_WIDTH = 100
+
+
+def console_factory(*args, **kwargs) -> Console:
+    """Utility to consolidate creation/initialization of Console.
+
+    A little hacky here... Allow terminal width to be set directly by an environment variable, or
+    when detecting that we're testing use a wide terminal to avoid line wrap issues.
+    """
+    width = kwargs.pop("width", None)
+    width_env = os.environ.get("TERMINAL_WIDTH")
+    pytest_version = os.environ.get("PYTEST_VERSION")
+    if width is not None:
+        pass
+    elif width_env is not None:
+        width = int(width_env)
+    elif pytest_version is not None:
+        width = TEST_TERMINAL_WIDTH
+    return Console(*args, width=width, **kwargs)
+
+

openapi_spec_tools-0.1.0/openapi_spec_tools/cli_gen/_display.py

@@ -0,0 +1,309 @@
+from enum import Enum
+from gettext import gettext
+from typing import Any
+from typing import Optional
+
+import yaml
+from rich.box import HEAVY_HEAD
+from rich.markup import escape
+from rich.table import Table
+
+from openapi_spec_tools.cli_gen._console import console_factory
+
+DEFAULT_ROW_PROPS = {
+    "justify": "left",
+    "no_wrap": True,
+    "overflow": "ignore",
+}
+
+# allow for i18n/l8n
+ITEMS = gettext("Items")
+PROPERTY = gettext("Property")
+PROPERTIES = gettext("Properties")
+VALUE = gettext("Value")
+VALUES = gettext("Values")
+UNKNOWN = gettext("Unknown")
+FOUND_ITEMS = gettext("Found {} items")
+ELLIPSIS = gettext("...")
+
+OBJECT_HEADERS = [PROPERTY, VALUE]
+
+KEY_FIELDS = ["name", "id"]
+URL_PREFIXES = ["http://", "https://", "ftp://"]
+
+KEY_MAX_LEN = 35
+VALUE_MAX_LEN = 50
+URL_MAX_LEN = 100
+
+
+# NOTE: the key field of dictionaries are expected to be be `str`, `int`, `float`, but use
+#       `Any` readability.
+
+
+class TableConfig:
+    """This data class provides a means for customizing the table outputs.
+
+    The defaults provide a standard look and feel, but can be overridden to all customization.
+    """
+
+    def __init__(
+        self,
+        items_label: str = ITEMS,
+        property_label: str = PROPERTY,
+        properties_label: str = PROPERTIES,
+        value_label: str = VALUE,
+        values_label: str = VALUES,
+        unknown_label: str = UNKNOWN,
+        items_caption: str = FOUND_ITEMS,
+        url_prefixes: list[str] = URL_PREFIXES,
+        url_max_len: int = URL_MAX_LEN,
+        key_fields: list[str] = KEY_FIELDS,
+        key_max_len: int = KEY_MAX_LEN,
+        value_max_len: int = VALUE_MAX_LEN,
+        row_properties: dict[str, Any] = DEFAULT_ROW_PROPS,
+    ):
+        self.items_label = items_label
+        self.property_label = property_label
+        self.properties_label = properties_label
+        self.value_label = value_label
+        self.values_label = values_label
+        self.unknown_label = unknown_label
+        self.items_caption = items_caption
+        self.url_prefixes = url_prefixes
+        self.url_max_len = url_max_len
+        self.key_fields = key_fields
+        self.key_max_len = key_max_len
+        self.value_max_len = value_max_len
+        self.row_properties = row_properties
+
+
+class RichTable(Table):
+    """
+    This is wrapper around the rich.Table to provide some methods for adding complex items.
+    """
+
+    def __init__(
+        self,
+        *args: Any,
+        outer: bool = True,
+        row_props: dict[str, Any] = DEFAULT_ROW_PROPS,
+        **kwargs: Any,
+    ):
+        super().__init__(
+            # items with "regular" defaults
+            highlight=kwargs.pop("highlight", True),
+            row_styles=kwargs.pop("row_styles", None),
+            expand=kwargs.pop("expand", False),
+            caption_justify=kwargs.pop("caption_justify", "left"),
+            border_style=kwargs.pop("border_style", None),
+            leading=kwargs.pop(
+                "leading", 0
+            ),  # warning: setting to non-zero disables lines
+            # these items take queues from `outer`
+            show_header=kwargs.pop("show_header", outer),
+            show_edge=kwargs.pop("show_edge", outer),
+            box=HEAVY_HEAD if outer else None,
+            **kwargs,
+        )
+        for name in args:
+            self.add_column(name, **row_props)
+
+
+def _truncate(s: str, max_length: int) -> str:
+    """Truncates the provided string to a maximum of max_length (including elipsis)"""
+    if len(s) < max_length:
+        return s
+    return s[: max_length - 3] + ELLIPSIS
+
+
+def _get_name_key(item: dict[Any, Any], key_fields: list[str]) -> Optional[str]:
+    """Attempts to find an identifying value."""
+    for k in key_fields:
+        key = str(k)
+        if key in item:
+            return key
+
+    return None
+
+
+def _is_url(s: str, url_prefixes: list[str]) -> bool:
+    """Rudimentary check for somethingt starting with URL prefix"""
+    return any(s.startswith(p) for p in url_prefixes)
+
+
+def _safe(v: Any) -> str:
+    """Converts 'v' to a string that is properly escaped."""
+    return escape(str(v))
+
+
+def _create_list_table(
+    items: list[dict[Any, Any]], outer: bool, config: TableConfig
+) -> RichTable:
+    """Creates a table from a list of dictionary items.
+
+    If an identifying "name key" is found (in the first entry), the table will have 2 columns: name, Properties
+    If no identifying "name key" is found, the table will be a single column table with the properties.
+
+    NOTE: nesting is done as needed
+    """
+    caption = config.items_caption.format(len(items)) if outer else None
+    name_key = _get_name_key(items[0], config.key_fields)
+    if not name_key:
+        # without identifiers just create table with one "Values" column
+        table = RichTable(
+            config.values_label,
+            outer=outer,
+            show_lines=True,
+            caption=caption,
+            row_props=config.row_properties,
+        )
+        for item in items:
+            table.add_row(_table_cell_value(item, config))
+        return table
+
+    # create a table with identifier in left column, and rest of data in right column
+    name_label = name_key[0].upper() + name_key[1:]
+    fields = [name_label, config.properties_label]
+    table = RichTable(
+        *fields,
+        outer=outer,
+        show_lines=True,
+        caption=caption,
+        row_props=config.row_properties,
+    )
+    for item in items:
+        # id may be an int, so convert to string before truncating
+        name = _safe(item.pop(name_key, config.unknown_label))
+        body = _table_cell_value(item, config)
+        table.add_row(_truncate(name, config.key_max_len), body)
+
+    return table
+
+
+def _create_object_table(
+    obj: dict[Any, Any], outer: bool, config: TableConfig
+) -> RichTable:
+    """Creates a table of a dictionary object.
+
+    NOTE: nesting is done in the right column as needed.
+    """
+    headers = [config.property_label, config.value_label]
+    table = RichTable(
+        *headers, outer=outer, show_lines=False, row_props=config.row_properties
+    )
+    for k, v in obj.items():
+        name = _safe(k)
+        table.add_row(_truncate(name, config.key_max_len), _table_cell_value(v, config))
+
+    return table
+
+
+def _table_cell_value(obj: Any, config: TableConfig) -> Any:
+    """Creates the "inner" value for a table cell.
+
+    Depending on the input value type, the cell may look different. If a dict, or list[dict],
+    an inner table is created. Otherwise, the object is converted to a printable value.
+    """
+    value: Any = None
+    if isinstance(obj, dict):
+        value = _create_object_table(obj, outer=False, config=config)
+    elif isinstance(obj, list) and obj:
+        if isinstance(obj[0], dict):
+            value = _create_list_table(obj, outer=False, config=config)
+        else:
+            values = [str(x) for x in obj]
+            s = _safe(", ".join(values))
+            value = _truncate(s, config.value_max_len)
+    else:
+        s = _safe(obj)
+        max_len = (
+            config.url_max_len
+            if _is_url(s, config.url_prefixes)
+            else config.value_max_len
+        )
+        value = _truncate(s, max_len)
+
+    return value
+
+
+def rich_table_factory(obj: Any, config: TableConfig = TableConfig()) -> RichTable:
+    """Create a RichTable (alias for rich.table.Table) from the object."""
+    if isinstance(obj, dict):
+        return _create_object_table(obj, outer=True, config=config)
+
+    if isinstance(obj, list) and obj and isinstance(obj[0], dict):
+        return _create_list_table(obj, outer=True, config=config)
+
+    # this is a list of "simple" properties
+    if (
+        isinstance(obj, list)
+        and obj
+        and all(
+            item is None or isinstance(item, (str, float, bool, int)) for item in obj
+        )
+    ):
+        caption = config.items_caption.format(len(obj))
+        table = RichTable(
+            config.items_label,
+            outer=True,
+            show_lines=True,
+            caption=caption,
+            row_props=config.row_properties,
+        )
+        for item in obj:
+            table.add_row(_table_cell_value(item, config))
+        return table
+
+    raise ValueError(f"Unable to create table for type {type(obj).__name__}")
+
+
+###################################################################################################
+# Below will remain even after the code from https://github.com/fastapi/typer/pull/1099 merges.
+###################################################################################################
+class OutputFormat(str, Enum):
+    TABLE = "table"
+    JSON = "json"
+    YAML = "yaml"
+
+
+class OutputStyle(str, Enum):
+    NONE = "none"
+    BOLD = "bold"
+    ALL = "all"
+
+
+def summary(obj: Any, properties: list[str]) -> Any:
+    """Gets the item with just the specified properties."""
+    if obj is None:
+        return None
+
+    if isinstance(obj, list):
+        # recursively call for each object in list
+        return [summary(item, properties) for item in obj]
+
+    return {prop: obj.get(prop) for prop in properties}
+
+
+def display(obj: Any, fmt: OutputFormat, style: OutputStyle, indent: int = 2) -> None:
+    """
+    This function handles display of the data provided in obj, according to the formating arguments.
+    """
+    no_color = style != OutputStyle.ALL
+    highlight = style != OutputStyle.NONE
+    console = console_factory(no_color=no_color, highlight=highlight)
+
+    if fmt == OutputFormat.JSON:
+        console.print_json(data=obj, indent=indent, highlight=highlight)
+        return
+
+    if fmt == OutputFormat.YAML:
+        console.print(_safe(yaml.dump(obj, indent=indent)))
+        return
+
+    if not obj:
+        console.print("Nothing found")
+        return
+
+    table = rich_table_factory(obj)
+    console.print(table)
+    return

openapi_spec_tools-0.1.0/openapi_spec_tools/cli_gen/_exceptions.py

@@ -0,0 +1,22 @@
+import typer
+from requests import HTTPError
+
+from openapi_spec_tools.cli_gen._console import console_factory
+
+
+class MissingRequiredError(Exception):
+    """Short wrapper to provde feedback about missing required options."""
+    def __init__(self, names: list[str]):
+        message = f"Missing required parameters, please provide: {', '.join(names)}"
+        super().__init__(message)
+
+
+def handle_exceptions(ex: Exception) -> None:
+    """Process exception and print a more concise error"""
+    if isinstance(ex, HTTPError):
+        message = str(ex.args[0])
+    else:
+        message = str(ex)
+    console = console_factory()
+    console.print(f"[red]ERROR:[/red] {message}")
+    raise typer.Exit(1)

openapi_spec_tools-0.1.0/openapi_spec_tools/cli_gen/_logging.py

@@ -0,0 +1,24 @@
+import logging
+from enum import Enum
+from typing import Optional
+
+LOG_CLASS = "cli"
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s %(message)s"
+LOG_DATE_FMT = "%Y-%m-%d %I:%M:%S %p"
+
+
+class LogLevel(str, Enum):
+    CRITICAL = "critical"
+    ERROR  = "error"
+    WARN = "warn"
+    INFO = "info"
+    DEBUG = "debug"
+
+
+def logger(name: Optional[str] = LOG_CLASS) -> logging.Logger:
+    return logging.getLogger(name=name)
+
+
+def init_logging(level: LogLevel, name: Optional[str] = LOG_CLASS):
+    logging.basicConfig(format=LOG_FORMAT, datefmt=LOG_DATE_FMT)
+    logger(name).setLevel(level.upper())