diff --git a/.readthedocs.yml b/.readthedocs.yml index 00d79f2..9a0a64c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -14,7 +14,7 @@ build: mkdocs: configuration: "mkdocs.yml" - fail_on_warning: false + fail_on_warning: true # Use our docs/requirements.txt during installation. python: diff --git a/docs/requirements.txt b/docs/requirements.txt index 24504dd..0d11b62 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,9 +1,10 @@ mkdocs==1.6.0 # Material for MkDocs theme -mkdocs-material==9.5.19 +mkdocs-material==9.5.32 # Render custom markdown for version added/changed/remove notes mkdocs-version-annotations==1.0.0 # Automatic documentation from sources, for MkDocs -mkdocstrings==0.24.3 -mkdocstrings-python==1.10.0 +griffe==1.1.1 +mkdocstrings-python==1.10.8 +mkdocstrings==0.25.2 markdown-data-tables==1.0.0 diff --git a/poetry.lock b/poetry.lock index cf69ed9..1aecf80 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand. [[package]] name = "astroid" @@ -334,13 +334,13 @@ dev = ["flake8", "markdown", "twine", "wheel"] [[package]] name = "griffe" -version = "0.47.0" +version = "1.1.1" description = "Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API." optional = false python-versions = ">=3.8" files = [ - {file = "griffe-0.47.0-py3-none-any.whl", hash = "sha256:07a2fd6a8c3d21d0bbb0decf701d62042ccc8a576645c7f8799fe1f10de2b2de"}, - {file = "griffe-0.47.0.tar.gz", hash = "sha256:95119a440a3c932b13293538bdbc405bee4c36428547553dc6b327e7e7d35e5a"}, + {file = "griffe-1.1.1-py3-none-any.whl", hash = "sha256:0c469411e8d671a545725f5c0851a746da8bd99d354a79fdc4abd45219252efb"}, + {file = "griffe-1.1.1.tar.gz", hash = "sha256:faeb78764c0b2bd010719d6e015d07709b0f260258b5d4dd6c88343d9702aa30"}, ] [package.dependencies] @@ -656,13 +656,13 @@ pyyaml = ">=5.1" [[package]] name = "mkdocs-material" -version = "9.5.29" +version = "9.5.32" description = "Documentation that simply works" optional = false python-versions = ">=3.8" files = [ - {file = "mkdocs_material-9.5.29-py3-none-any.whl", hash = "sha256:afc1f508e2662ded95f0a35a329e8a5acd73ee88ca07ba73836eb6fcdae5d8b4"}, - {file = "mkdocs_material-9.5.29.tar.gz", hash = "sha256:3e977598ec15a4ddad5c4dfc9e08edab6023edb51e88f0729bd27be77e3d322a"}, + {file = "mkdocs_material-9.5.32-py3-none-any.whl", hash = "sha256:f3704f46b63d31b3cd35c0055a72280bed825786eccaf19c655b44e0cd2c6b3f"}, + {file = "mkdocs_material-9.5.32.tar.gz", hash = "sha256:38ed66e6d6768dde4edde022554553e48b2db0d26d1320b19e2e2b9da0be1120"}, ] [package.dependencies] @@ -707,13 +707,13 @@ files = [ [[package]] name = "mkdocstrings" -version = "0.24.3" +version = "0.25.2" description = "Automatic documentation from sources, for MkDocs." optional = false python-versions = ">=3.8" files = [ - {file = "mkdocstrings-0.24.3-py3-none-any.whl", hash = "sha256:5c9cf2a32958cd161d5428699b79c8b0988856b0d4a8c5baf8395fc1bf4087c3"}, - {file = "mkdocstrings-0.24.3.tar.gz", hash = "sha256:f327b234eb8d2551a306735436e157d0a22d45f79963c60a8b585d5f7a94c1d2"}, + {file = "mkdocstrings-0.25.2-py3-none-any.whl", hash = "sha256:9e2cda5e2e12db8bb98d21e3410f3f27f8faab685a24b03b06ba7daa5b92abfc"}, + {file = "mkdocstrings-0.25.2.tar.gz", hash = "sha256:5cf57ad7f61e8be3111a2458b4e49c2029c9cb35525393b179f9c916ca8042dc"}, ] [package.dependencies] @@ -735,18 +735,18 @@ python-legacy = ["mkdocstrings-python-legacy (>=0.2.1)"] [[package]] name = "mkdocstrings-python" -version = "1.10.0" +version = "1.10.8" description = "A Python handler for mkdocstrings." optional = false python-versions = ">=3.8" files = [ - {file = "mkdocstrings_python-1.10.0-py3-none-any.whl", hash = "sha256:ba833fbd9d178a4b9d5cb2553a4df06e51dc1f51e41559a4d2398c16a6f69ecc"}, - {file = "mkdocstrings_python-1.10.0.tar.gz", hash = "sha256:71678fac657d4d2bb301eed4e4d2d91499c095fd1f8a90fa76422a87a5693828"}, + {file = "mkdocstrings_python-1.10.8-py3-none-any.whl", hash = "sha256:bb12e76c8b071686617f824029cb1dfe0e9afe89f27fb3ad9a27f95f054dcd89"}, + {file = "mkdocstrings_python-1.10.8.tar.gz", hash = "sha256:5856a59cbebbb8deb133224a540de1ff60bded25e54d8beacc375bb133d39016"}, ] [package.dependencies] -griffe = ">=0.44" -mkdocstrings = ">=0.24.2" +griffe = ">=0.49" +mkdocstrings = ">=0.25" [[package]] name = "mypy-extensions" @@ -1006,6 +1006,7 @@ files = [ {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"}, {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"}, {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"}, + {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"}, {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"}, {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"}, {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"}, @@ -1403,4 +1404,4 @@ test = ["big-O", "importlib-resources", "jaraco.functools", "jaraco.itertools", [metadata] lock-version = "2.0" python-versions = "^3.8.1" -content-hash = "c1c4eeb164e71096078d940f19728d6fa2f7c72e742d98930a1ef307aa0d5d8c" +content-hash = "05a10ab2f8c29372c3c381f2e21e4d4e5a0ac6e856e5b8e2f3dc83eb22ffdaab" diff --git a/pynautobot/core/api.py b/pynautobot/core/api.py index 0dd6596..902acb4 100644 --- a/pynautobot/core/api.py +++ b/pynautobot/core/api.py @@ -126,7 +126,7 @@ def version(self): if specific features or syntaxes are available. Returns: - str: The Nautobot API version string. + (str): The Nautobot API version string. Raises: requests.exceptions.RequestException: If there is an error fetching the @@ -158,7 +158,7 @@ def openapi(self): This can be useful for tools like code generation or API clients in other languages. Returns: - dict: The OpenAPI specification document as a Python dictionary. + (dict): The OpenAPI specification document as a Python dictionary. Raises: requests.exceptions.RequestException: If there is an error fetching the @@ -196,7 +196,7 @@ def status(self): **Availability:** Requires Nautobot version 2.10.0 or newer. Returns: - dict: A dictionary containing the status information as returned by Nautobot. + (dict): A dictionary containing the status information as returned by Nautobot. Raises: pynautobot.exceptions.RequestError: If the request to Nautobot fails. diff --git a/pynautobot/core/app.py b/pynautobot/core/app.py index c93dd1b..68c7f65 100644 --- a/pynautobot/core/app.py +++ b/pynautobot/core/app.py @@ -29,7 +29,7 @@ class App(object): Calls to attributes are returned as Endpoint objects. Returns: - Endpoint: Matching requested attribute. + (Endpoint): Matching requested attribute. Raises: RequestError: If requested endpoint doesn't exist. @@ -77,7 +77,7 @@ def choices(self): """Returns _choices response from App. Returns: - Raw response from Nautobot's _choices endpoint. + (List[Response]): Raw response from Nautobot's _choices endpoint. """ if self._choices: return self._choices @@ -94,7 +94,7 @@ def get_custom_fields(self): """Returns custom-fields response from app. Returns: - Raw response from Nautobot's custom-fields endpoint. + (List[Response]): Raw response from Nautobot's custom-fields endpoint. Raises: RequestError: If called for an invalid endpoint. @@ -135,7 +135,7 @@ def get_custom_field_choices(self): """Returns custom-field-choices response from app. Returns: - Raw response from Nautobot's custom-field-choices endpoint. + (List[Response]): Raw response from Nautobot's custom-field-choices endpoint. Raises: RequestError: If called for an invalid endpoint. @@ -170,7 +170,7 @@ def config(self): """Returns config response from app. Returns: - dict: Raw response from Nautobot's config endpoint. + (dict): Raw response from Nautobot's config endpoint. Raises: RequestError: If called for an invalid endpoint. @@ -215,7 +215,7 @@ class PluginsApp(object): but you need to add "plugins" to the request URL path. Returns: - App: With "plugins" added to the path. + (App): With "plugins" added to the path. """ def __init__(self, api): @@ -234,7 +234,7 @@ def installed_plugins(self): """Returns raw response with installed plugins. Returns: - Raw response from Nautobot's installed plugins. + (List[Response]): Raw response from Nautobot's installed plugins. Examples: >>> nb.plugins.installed_plugins() diff --git a/pynautobot/core/endpoint.py b/pynautobot/core/endpoint.py index df43a11..ec6395a 100644 --- a/pynautobot/core/endpoint.py +++ b/pynautobot/core/endpoint.py @@ -72,7 +72,7 @@ def _lookup_ret_obj(self, name, model): model (obj): The application model that contains unique Record objects. Returns: - Record: Unique response object if exists, otherwise a generic `Record` object. + (Record): Unique response object if exists, otherwise a generic `Record` object. """ if model: name = name.title().replace("_", "").replace("-", "") @@ -86,7 +86,7 @@ def all(self, *args, **kwargs): Returns all objects from an endpoint. - Args: + Optional Args: api_version (str, optional): Override default or globally-set Nautobot REST API version for this single request. limit (int, optional): Overrides the max page size on @@ -95,7 +95,7 @@ def all(self, *args, **kwargs): will be made as you iterate through the result set. offset (int, optional): Overrides the offset on paginated returns. Returns: - list: List of :py:class:`.Record` objects. + (list): List of :py:class:`.Record` objects. Examples: >>> nb.dcim.devices.all() @@ -106,7 +106,7 @@ def all(self, *args, **kwargs): def get(self, *args, **kwargs): """Queries the DetailsView of a given endpoint. - Args: + Optional Args: key (int, optional): ID for the item to be retrieved. **kwargs (str, optional): Accepts the same keyword args as filter(). Any search argument the endpoint accepts can be added as a keyword arg. @@ -114,7 +114,7 @@ def get(self, *args, **kwargs): version for this single request. Returns: - Union[Record, None]: A single :py:class:`.Record` object or None. + (Union[Record, None]): A single :py:class:`.Record` object or None. Raises: ValueError: If kwarg search returns more than one value. @@ -184,7 +184,7 @@ def filter(self, *args, api_version=None, **kwargs): Nautobot REST API version for this single request. Returns: - list: A list of :py:class:`.Record` objects. + (list): A list of :py:class:`.Record` objects. Examples: To return a list of objects matching a named argument filter. @@ -248,7 +248,7 @@ def create(self, *args, api_version=None, **kwargs): Nautobot REST API version for this single request. Returns: - Union[Record, List[Record]]: A list or single :py:class:`.Record` object depending + (Union[Record, List[Record]]): A list or single :py:class:`.Record` object depending on whether a bulk creation was requested. Examples: @@ -303,11 +303,11 @@ def update(self, *args, **kwargs): **kwargs (str, optional): See Below. Keyword Arguments: - * *id* (``string``) -- Identifier of the object being updated. - * *data* (``dict``) -- Key/value pairs to update the record object with. + id (string): Identifier of the object being updated. + data (dict): Key/value pairs to update the record object with. Returns: - Union[Record, List[Record]]: A list or single :py:class:`.Record` object depending + (Union[Record, List[Record]]): A list or single :py:class:`.Record` object depending on whether a bulk update was requested. Examples: @@ -409,7 +409,7 @@ def delete(self, objects): objects (list): A list of either IDs or Records to delete. Returns: - bool: True if bulk DELETE operation was successful. + (bool): True if bulk DELETE operation was successful. Examples: Deleting all `devices`: @@ -469,7 +469,7 @@ def choices(self, api_version=None): Nautobot REST API version for this single request. Returns: - dict: Dict containing the available choices. + (dict): Dict containing the available choices. Example (from Nautobot 2.8.x): >>> from pprint import pprint @@ -527,7 +527,7 @@ def count(self, *args, api_version=None, **kwargs): Nautobot REST API version for this single request. Returns: - int: Integer with count of objects returned by query. + (int): Integer with count of objects returned by query. Examples: To return a count of objects matching a named argument filter. @@ -579,11 +579,11 @@ def list(self, api_version=None, **kwargs): Args: api_version (str, optional): Override default or globally set Nautobot REST API version for this single request. - **kwargs: Key/value pairs that get converted into URL parameters when passed to the endpoint. + **kwargs (dict): Key/value pairs that get converted into URL parameters when passed to the endpoint. E.g. ``.list(method='get_facts')`` would be converted to ``.../?method=get_facts``. Returns: - Union[Dict, List[Dict]]: A dictionary or list of dictionaries retrieved from Nautobot. + (Union[Dict, List[Dict]]): A dictionary or list of dictionaries retrieved from Nautobot. """ api_version = api_version or self.parent_obj.api.api_version @@ -608,7 +608,7 @@ def create(self, data=None, api_version=None): Nautobot REST API version for this single request. Returns: - Union[Dict, List[Dict]]: A dictionary or list of dictionaries representing + (Union[Dict, List[Dict]]): A dictionary or list of dictionaries representing the items created in Nautobot. """ data = data or {} @@ -642,7 +642,7 @@ def run(self, *args, api_version=None, **kwargs): Nautobot REST API version for this single request. Returns: - obj: Job details: job_result object uuid found at `obj.result.id`. + obj (str): Job details: job_result object uuid found at `obj.result.id`. Examples: To run a job for verifying hostnames: @@ -693,7 +693,7 @@ def run(self, query_id, *args, **kwargs): that is being ran. Returns: - An API response from the execution of the saved graphql query. + (Response): An API response from the execution of the saved graphql query. Examples: To run a query no variables: diff --git a/pynautobot/core/query.py b/pynautobot/core/query.py index ebeb7d5..d1662ee 100644 --- a/pynautobot/core/query.py +++ b/pynautobot/core/query.py @@ -192,7 +192,7 @@ def get_version(self): RequestError: If req.ok returns false. Returns: - str: Version number as a string. Empty string if version is not present in the headers. + (str): Version number as a string. Empty string if version is not present in the headers. """ headers = { "Content-Type": "application/json;", @@ -218,7 +218,7 @@ def get_status(self): """Gets the status from /api/status/ endpoint in Nautobot. Returns: - dict: Dictionary as returned by Nautobot. + (dict): Dictionary as returned by Nautobot. Raises: RequestError: If request is not successful. @@ -315,7 +315,7 @@ def get(self, add_params=None): ContentError: If response is not JSON. Returns: - List[Response]: List of `Response` objects returned from the + (List[Response]): List of `Response` objects returned from the endpoint. """ if not add_params and self.limit is not None: @@ -375,7 +375,7 @@ def put(self, data: dict) -> dict: ContentError: If the response cannot be deserialized from JSON. Returns: - dict: The deserialized JSON response from the Nautobot API. + (dict): The deserialized JSON response from the Nautobot API. """ return self._make_call(verb="put", data=data) @@ -393,7 +393,7 @@ def post(self, data: dict) -> dict: ContentError: If the response cannot be deserialized from JSON. Returns: - dict: The deserialized JSON response from the Nautobot API. + (dict): The deserialized JSON response from the Nautobot API. """ return self._make_call(verb="post", data=data) @@ -407,7 +407,7 @@ def delete(self, data=None): and sent to the API. Returns: - bool: True if successful. + (bool): True if successful. Raises: RequestError: If req.ok doesn't return True. @@ -441,7 +441,7 @@ def options(self) -> dict: ContentError: If the response cannot be deserialized from JSON. Returns: - dict: The deserialized JSON response from the Nautobot API, + (dict): The deserialized JSON response from the Nautobot API, containing information about allowed methods. """ @@ -456,9 +456,9 @@ def get_count(self, *args, **kwargs) -> int: with the same parameters. Args: - *args: Additional positional arguments to be passed to the + *args (list): Additional positional arguments to be passed to the Nautobot API endpoint. - **kwargs: Additional keyword arguments to be passed to the + **kwargs (dict): Additional keyword arguments to be passed to the Nautobot API endpoint. Raises: @@ -466,7 +466,7 @@ def get_count(self, *args, **kwargs) -> int: ContentError: If the response cannot be deserialized from JSON. Returns: - int: The total number of objects that would match the provided query. + (int): The total number of objects that would match the provided query. """ return self._make_call(add_params={"limit": 1})["count"] diff --git a/pynautobot/core/response.py b/pynautobot/core/response.py index decca8d..f00c1d8 100644 --- a/pynautobot/core/response.py +++ b/pynautobot/core/response.py @@ -32,13 +32,10 @@ def get_return(lookup, return_fields=None): """Returns simple representations for items passed to lookup. Args: - lookup: The object or collection to retrieve representations for. + lookup (dict|Record): The object or collection to retrieve representations for. return_fields (list, optional): A list of fields to reference when calling values on lookup. - Returns: - The simple representation of the object or collection. - Note: Used to return a "simple" representation of objects and collections sent to it via lookup. Otherwise, we look to see if @@ -171,7 +168,7 @@ def __getattr__(self, k): k (str): The name of the attribute. Returns: - Any: The value of the requested attribute. + (Any): The value of the requested attribute. Raises: AttributeError: If the attribute is not found. @@ -299,8 +296,7 @@ def full_details(self): attribute when it's called to prevent being called more than once. - Returns: - True + Returns: (bool) """ if self.url: req = Request( @@ -325,7 +321,7 @@ def serialize(self, nested=False, init=False): init (bool): Whether to include initialization attributes in the serialization. Default is False. Returns: - dict: A dictionary representation of the serialized object. + (dict): A dictionary representation of the serialized object. Note: Using this method to get a dictionary representation of the record @@ -377,7 +373,7 @@ def updates(self): have been made. Returns: - dict: A dictionary containing the changes made to the object. + (dict): A dictionary containing the changes made to the object. Examples: >>> x = nb.dcim.devices.get(name='test1234') @@ -401,7 +397,7 @@ def save(self): and sends them as a dictionary to Request.patch(). Returns: - bool: True if the PATCH request was successful. + (bool): True if the PATCH request was successful. Examples: >>> x = nb.dcim.devices.get(name='test1-a3-tor1b') @@ -439,7 +435,7 @@ def update(self, data): the record object with. Returns: - bool: True if the PATCH request was successful. + (bool): True if the PATCH request was successful. Examples: >>> x = nb.dcim.devices.get(1) @@ -458,7 +454,7 @@ def delete(self): """Deletes an existing object. Returns: - bool: True if the DELETE operation was successful. + (bool): True if the DELETE operation was successful. Examples: >>> x = nb.dcim.devices.get(name='test1-a3-tor1b') diff --git a/pyproject.toml b/pyproject.toml index 621b21e..68b7077 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -30,9 +30,10 @@ requests-mock = "^1.12.1" pytest = "^8.1.1" mkdocs = "^1.6.0" watchdog = "^4.0.0" -mkdocs-material = "^9.5.19" -mkdocstrings = "^0.24.3" -mkdocstrings-python = "^1.10.0" +mkdocs-material = "9.5.32" +mkdocstrings = "0.25.2" +mkdocstrings-python = "1.10.8" +griffe = "1.1.1" markdown-data-tables = "^1.0.0" mkdocs-version-annotations = "^1.0.0" pyyaml = "^6.0.1"