From 5555de62426063483196888f1bc73757e7492ce8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 10 Jul 2024 17:22:20 +0200 Subject: [PATCH] refactor: Renamed `dataclasses` internal modules to `models` --- docs/extensions.md | 24 +++---- docs/loading.md | 38 +++++------ docs/parsing_docstrings.md | 6 +- docs/schema.json | 66 +++++++++---------- docs/try_it_out.md | 2 +- src/_griffe/__init__.py | 2 +- src/_griffe/agents/inspector.py | 4 +- src/_griffe/agents/nodes/_all.py | 2 +- src/_griffe/agents/nodes/_imports.py | 2 +- src/_griffe/agents/visitor.py | 4 +- src/_griffe/collections.py | 2 +- src/_griffe/diff.py | 2 +- src/_griffe/docstrings/google.py | 4 +- .../docstrings/{dataclasses.py => models.py} | 2 +- src/_griffe/docstrings/numpy.py | 4 +- src/_griffe/docstrings/parsers.py | 4 +- src/_griffe/docstrings/sphinx.py | 4 +- src/_griffe/docstrings/utils.py | 2 +- src/_griffe/encoders.py | 2 +- src/_griffe/exceptions.py | 2 +- src/_griffe/expressions.py | 2 +- src/_griffe/extensions/base.py | 2 +- src/_griffe/extensions/dataclasses.py | 2 +- src/_griffe/finder.py | 2 +- src/_griffe/loader.py | 8 +-- src/_griffe/merger.py | 2 +- src/_griffe/mixins.py | 2 +- src/_griffe/{dataclasses.py => models.py} | 24 +++---- src/_griffe/stats.py | 2 +- src/_griffe/tests.py | 2 +- tests/test_dataclasses.py | 14 ++-- tests/test_docstrings/helpers.py | 4 +- tests/test_docstrings/test_google.py | 4 +- tests/test_docstrings/test_numpy.py | 4 +- tests/test_docstrings/test_sphinx.py | 4 +- tests/test_docstrings/test_warnings.py | 2 +- tests/test_encoders.py | 2 +- tests/test_expressions.py | 2 +- tests/test_extensions.py | 2 +- tests/test_finder.py | 2 +- tests/test_functions.py | 2 +- tests/test_git.py | 2 +- tests/test_inheritance.py | 2 +- tests/test_loader.py | 2 +- tests/test_stdlib.py | 2 +- 45 files changed, 138 insertions(+), 138 deletions(-) rename src/_griffe/docstrings/{dataclasses.py => models.py} (99%) rename src/_griffe/{dataclasses.py => models.py} (98%) diff --git a/docs/extensions.md b/docs/extensions.md index 390ff097..8bb9a280 100644 --- a/docs/extensions.md +++ b/docs/extensions.md @@ -146,11 +146,11 @@ both the visitor and inspector agents will trigger events. These events can be hooked on by extensions to alter or enhance Griffe's behavior. Some hooks will be passed just the current node being visited, others will be passed both the node -and an instance of an [Object][griffe.dataclasses.Object] subclass, -such as a [Module][griffe.dataclasses.Module], -a [Class][griffe.dataclasses.Class], -a [Function][griffe.dataclasses.Function], -or an [Attribute][griffe.dataclasses.Attribute]. +and an instance of an [Object][griffe.models.Object] subclass, +such as a [Module][griffe.models.Module], +a [Class][griffe.models.Class], +a [Function][griffe.models.Function], +or an [Attribute][griffe.models.Attribute]. Extensions will therefore be able to modify these instances. The following flow chart shows an example of an AST visit. @@ -180,11 +180,11 @@ contains a single class, which itself contains a single method: - the agent (visitor or inspector) will walk through the tree by starting with the module node -- it will instantiate a [Module][griffe.dataclasses.Module], +- it will instantiate a [Module][griffe.models.Module], then walk through its members, continuing with the class node -- it will instantiate a [Class][griffe.dataclasses.Class], +- it will instantiate a [Class][griffe.models.Class], then walk through its members, continuing with the function node -- it will instantiate a [Function][griffe.dataclasses.Function] +- it will instantiate a [Function][griffe.models.Function] - then it will go back up and finish walking since there are no more nodes to walk through @@ -296,10 +296,10 @@ The "on node" events are triggered when the agent (visitor or inspector) starts handling a node in the tree (AST or object tree). The "on instance" events are triggered when the agent -just created an instance of [Module][griffe.dataclasses.Module], -[Class][griffe.dataclasses.Class], -[Function][griffe.dataclasses.Function], -or [Attribute][griffe.dataclasses.Attribute], +just created an instance of [Module][griffe.models.Module], +[Class][griffe.models.Class], +[Function][griffe.models.Function], +or [Attribute][griffe.models.Attribute], and added it as a member of its parent. The "on members" events are triggered when the agent diff --git a/docs/loading.md b/docs/loading.md index 4e412937..2e6069b8 100644 --- a/docs/loading.md +++ b/docs/loading.md @@ -31,24 +31,24 @@ mkdocs = loader.load("mkdocs", submodules=False) ## Navigating into the loaded objects Both the `load` function and the `GriffeLoader.load` method -return an [`Object`][griffe.dataclasses.Object] instance. +return an [`Object`][griffe.models.Object] instance. There are several ways to access members of an object: - through its `members` attribute, which is a dictionary, with the usual `keys()`, `values()` and `items()` methods. -- thanks to its `__getitem__` method. For example `griffe["dataclasses"]` - returns the `Module` instance representing Griffe's `dataclasses` module. - Since this module also has members, you can chain calls: `griffe["dataclasses"]["Module"]`. - Conveniently, you can chain the names with dots in a single call: `griffe["dataclasses.Module"]`. - You can even pass a tuple instead of a string: `griffe[("dataclasses", "Module")]`. -- through the [`modules`][griffe.dataclasses.Object.modules], - [`classes`][griffe.dataclasses.Object.classes], - [`functions`][griffe.dataclasses.Object.functions] and - [`attributes`][griffe.dataclasses.Object.attributes] properties, +- thanks to its `__getitem__` method. For example `griffe["models"]` + returns the `Module` instance representing Griffe's `models` module. + Since this module also has members, you can chain calls: `griffe["models"]["Module"]`. + Conveniently, you can chain the names with dots in a single call: `griffe["models.Module"]`. + You can even pass a tuple instead of a string: `griffe[("models", "Module")]`. +- through the [`modules`][griffe.models.Object.modules], + [`classes`][griffe.models.Object.classes], + [`functions`][griffe.models.Object.functions] and + [`attributes`][griffe.models.Object.attributes] properties, which take care of filtering members based on their kind, and return dictionaries. -Most of the time, you will only use classes from the [`griffe.dataclasses`][griffe.dataclasses] -and [`griffe.docstrings.dataclasses`][griffe.docstrings.dataclasses] modules. +Most of the time, you will only use classes from the [`griffe.models`][griffe.models] +and [`griffe.docstrings.models`][griffe.docstrings.models] modules. ## Class inheritance @@ -64,7 +64,7 @@ from using inheritance support in Griffe. Griffe supports class inheritance, both when visiting and inspecting modules. To access members of a class that are inherited from base classes, -use [`Object.inherited_members`][griffe.dataclasses.Object.inherited_members]. +use [`Object.inherited_members`][griffe.models.Object.inherited_members]. If this is the first time you access inherited members, the base classes of the given class will be resolved and cached, then the MRO (Method Resolution Order) will be computed for these bases classes, and a dictionary of inherited members @@ -94,15 +94,15 @@ If a base class cannot be resolved during computation of inherited members, Griffe logs a DEBUG message. If you want to access all members at once (both declared and inherited), -use [`Object.all_members`][griffe.dataclasses.Object.all_members]. +use [`Object.all_members`][griffe.models.Object.all_members]. If you want to access only declared members, -use [`Object.members`][griffe.dataclasses.Object]. +use [`Object.members`][griffe.models.Object]. -Accessing [`Object.attributes`][griffe.dataclasses.Object.attributes], -[`Object.functions`][griffe.dataclasses.Object.functions], -[`Object.classes`][griffe.dataclasses.Object.classes] or -[`Object.modules`][griffe.dataclasses.Object.modules] +Accessing [`Object.attributes`][griffe.models.Object.attributes], +[`Object.functions`][griffe.models.Object.functions], +[`Object.classes`][griffe.models.Object.classes] or +[`Object.modules`][griffe.models.Object.modules] will trigger inheritance computation, so make sure to only call it once everything is loaded by Griffe. Don't access inherited members in extensions, while visiting or inspecting a module. diff --git a/docs/parsing_docstrings.md b/docs/parsing_docstrings.md index 71ed8e1e..dc6eef77 100644 --- a/docs/parsing_docstrings.md +++ b/docs/parsing_docstrings.md @@ -2,12 +2,12 @@ You can use Griffe to parse arbitrary docstrings. You don't have to load anything through the Griffe loader. -You just need to import the [`Docstring`][griffe.dataclasses.Docstring] class. +You just need to import the [`Docstring`][griffe.models.Docstring] class. Then you can build a `Docstring` instance and call its `parse` method, choosing the parsing-style to use: ```python -from griffe.dataclasses import Docstring +from griffe.models import Docstring text = "Hello I'm a docstring!" docstring = Docstring(text, lineno=1) @@ -19,7 +19,7 @@ annotations from the object from which the docstring originates, you can manually create the parent objects and link them to the docstring: ```python -from griffe.dataclasses import Docstring, Function, Parameters, Parameter, ParameterKind +from griffe.models import Docstring, Function, Parameters, Parameter, ParameterKind function = Function( "func", diff --git a/docs/schema.json b/docs/schema.json index 4476bd6e..08bdefae 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -7,32 +7,32 @@ "properties": { "name": { "title": "The name of the alias.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.name", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Alias.name", "type": "string" }, "kind": { "title": "The 'alias' kind.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.kind", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Alias.kind", "const": "alias" }, "path": { "title": "The alias path.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.path", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Alias.path", "type": "string" }, "target_path": { "title": "For aliases, the Python path of their target.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.target_path", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Alias.target_path", "type": "string" }, "lineno": { "title": "For aliases, the import starting line number in their own module.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.lineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Alias.lineno", "type": "integer" }, "endlineno": { "title": "For aliases, the import ending line number in their own module.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.endlineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Alias.endlineno", "type": [ "integer", "null" @@ -53,12 +53,12 @@ "properties": { "name": { "title": "The name of the object.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.name", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.name", "type": "string" }, "kind": { "title": "The kind of object.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.kind", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.kind", "enum": [ "module", "class", @@ -68,47 +68,47 @@ }, "path": { "title": "The path of the object (dot-separated Python path).", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.path", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.path", "type": "string" }, "filepath": { "title": "The file path of the object's parent module.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.filepath", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.filepath", "type": "string" }, "relative_filepath": { "title": "The file path of the object's parent module, relative to the (at the time) current working directory.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.relative_filepath", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.relative_filepath", "type": "string" }, "relative_package_filepath": { "title": "The file path of the object's package, as found in the explored directories of the Python paths.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.relative_package_filepath", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.relative_package_filepath", "type": "string" }, "labels": { "title": "The labels of the object.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.labels", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Object.labels", "type": "array" }, "docstring": { "title": "The docstring of the object.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring", "type": "object", "properties": { "value": { "title": "The actual string.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.value", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring.value", "type": "string" }, "lineno": { "title": "The docstring starting line number.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.lineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring.lineno", "type": "integer" }, "endlineno": { "title": "The docstring ending line number.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.endlineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring.endlineno", "type": [ "integer", "null" @@ -116,7 +116,7 @@ }, "parsed": { "title": "The parsed docstring (list of docstring sections).", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.parsed", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring.parsed", "type": "array", "items": { "type": "object", @@ -167,12 +167,12 @@ }, "lineno": { "title": "The docstring starting line number.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.lineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring.lineno", "type": "integer" }, "endlineno": { "title": "The docstring ending line number.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.endlineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Docstring.endlineno", "type": [ "integer", "null" @@ -209,7 +209,7 @@ "properties": { "bases": { "title": "For classes, their bases classes.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Class.bases", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Class.bases", "type": "array", "items": { "$ref": "#/$defs/annotation" @@ -217,24 +217,24 @@ }, "decorators": { "title": "For classes, their decorators.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Class.decorators", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Class.decorators", "type": "array", "items": { "type": "object", "properties": { "value": { "title": "The decorator value (string, name or expression).", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Decorator.value", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Decorator.value", "$ref": "#/$defs/annotation" }, "lineno": { "title": "The decorator starting line number.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Decorator.lineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Decorator.lineno", "type": "integer" }, "endlineno": { "title": "The decorator ending line number.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Decorator.endlineno", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Decorator.endlineno", "type": [ "integer", "null" @@ -268,29 +268,29 @@ "properties": { "parameters": { "title": "For functions, their parameters.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Function.parameters", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Function.parameters", "type": "array", "items": { "type": "object", "properties": { "name": { "title": "The name of the parameter.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Parameter.name", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Parameter.name", "type": "string" }, "annotation": { "title": "The annotation of the parameter.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Parameter.annotation", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Parameter.annotation", "$ref": "#/$defs/annotation" }, "kind": { "title": "The kind of parameter.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Parameter.kind", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Parameter.kind", "type": "string" }, "default": { "title": "The default value of the parameter.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Parameter.default", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Parameter.default", "$ref": "#/$defs/annotation" } }, @@ -302,7 +302,7 @@ }, "returns": { "title": "For functions, their return annotation.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Function.returns", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Function.returns", "$ref": "#/$defs/annotation" } }, @@ -324,12 +324,12 @@ "properties": { "value": { "title": "For attributes, their value.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Attribute.value", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Attribute.value", "$ref": "#/$defs/annotation" }, "annotation": { "title": "For attributes, their type annotation.", - "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Attribute.annotation", + "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/models/#griffe.models.Attribute.annotation", "$ref": "#/$defs/annotation" } } diff --git a/docs/try_it_out.md b/docs/try_it_out.md index 39f58732..543f54c6 100644 --- a/docs/try_it_out.md +++ b/docs/try_it_out.md @@ -11,7 +11,7 @@ Then we output the signature of the `Function` class as JSON. ```pyodide install="griffe" import griffe griffe_pkg = griffe.load("griffe") -griffe_pkg["dataclasses.Function"].as_json(indent=2) +griffe_pkg["models.Function"].as_json(indent=2) ``` Try it out with another package of your choice! diff --git a/src/_griffe/__init__.py b/src/_griffe/__init__.py index a992ec4b..ff3fe315 100644 --- a/src/_griffe/__init__.py +++ b/src/_griffe/__init__.py @@ -8,7 +8,7 @@ from __future__ import annotations from griffe.agents.nodes import ObjectNode -from griffe.dataclasses import Attribute, Class, Docstring, Function, Module, Object +from griffe.models import Attribute, Class, Docstring, Function, Module, Object from griffe.diff import find_breaking_changes from griffe.docstrings.google import parse as parse_google from griffe.docstrings.numpy import parse as parse_numpy diff --git a/src/_griffe/agents/inspector.py b/src/_griffe/agents/inspector.py index cede6427..ed61685d 100644 --- a/src/_griffe/agents/inspector.py +++ b/src/_griffe/agents/inspector.py @@ -12,7 +12,7 @@ This module exposes a public function, [`inspect()`][griffe.agents.inspector.inspect], which inspects the module using [`inspect.getmembers()`][inspect.getmembers], -and returns a new [`Module`][griffe.dataclasses.Module] instance, +and returns a new [`Module`][griffe.models.Module] instance, populating its members recursively, by using a [`NodeVisitor`][ast.NodeVisitor]-like class. The inspection agent works similarly to the regular "node visitor" agent, @@ -30,7 +30,7 @@ from griffe.agents.nodes import ObjectNode from griffe.collections import LinesCollection, ModulesCollection -from griffe.dataclasses import Alias, Attribute, Class, Docstring, Function, Module, Parameter, Parameters +from griffe.models import Alias, Attribute, Class, Docstring, Function, Module, Parameter, Parameters from griffe.enumerations import ObjectKind, ParameterKind from griffe.expressions import safe_get_annotation from griffe.extensions.base import Extensions, load_extensions diff --git a/src/_griffe/agents/nodes/_all.py b/src/_griffe/agents/nodes/_all.py index 32f06721..b12c892b 100644 --- a/src/_griffe/agents/nodes/_all.py +++ b/src/_griffe/agents/nodes/_all.py @@ -11,7 +11,7 @@ from griffe.logger import LogLevel, get_logger if TYPE_CHECKING: - from griffe.dataclasses import Module + from griffe.models import Module logger = get_logger(__name__) diff --git a/src/_griffe/agents/nodes/_imports.py b/src/_griffe/agents/nodes/_imports.py index 031fd73b..2c60398d 100644 --- a/src/_griffe/agents/nodes/_imports.py +++ b/src/_griffe/agents/nodes/_imports.py @@ -9,7 +9,7 @@ if TYPE_CHECKING: import ast - from griffe.dataclasses import Module + from griffe.models import Module logger = get_logger(__name__) diff --git a/src/_griffe/agents/visitor.py b/src/_griffe/agents/visitor.py index 113fef97..09b4b0ad 100644 --- a/src/_griffe/agents/visitor.py +++ b/src/_griffe/agents/visitor.py @@ -2,7 +2,7 @@ This module exposes a public function, [`visit()`][griffe.agents.visitor.visit], which parses the module code using [`parse()`][ast.parse], -and returns a new [`Module`][griffe.dataclasses.Module] instance, +and returns a new [`Module`][griffe.models.Module] instance, populating its members recursively, by using a [`NodeVisitor`][ast.NodeVisitor]-like class. """ @@ -24,7 +24,7 @@ safe_get__all__, ) from griffe.collections import LinesCollection, ModulesCollection -from griffe.dataclasses import Alias, Attribute, Class, Decorator, Docstring, Function, Module, Parameter, Parameters +from griffe.models import Alias, Attribute, Class, Decorator, Docstring, Function, Module, Parameter, Parameters from griffe.enumerations import Kind from griffe.exceptions import AliasResolutionError, CyclicAliasError, LastNodeError from griffe.expressions import ( diff --git a/src/_griffe/collections.py b/src/_griffe/collections.py index 2ba82322..cdb5eecb 100644 --- a/src/_griffe/collections.py +++ b/src/_griffe/collections.py @@ -9,7 +9,7 @@ if TYPE_CHECKING: from pathlib import Path - from griffe.dataclasses import Module + from griffe.models import Module class LinesCollection: diff --git a/src/_griffe/diff.py b/src/_griffe/diff.py index 3bb75a32..fa7ba14b 100644 --- a/src/_griffe/diff.py +++ b/src/_griffe/diff.py @@ -15,7 +15,7 @@ from griffe.logger import get_logger if TYPE_CHECKING: - from griffe.dataclasses import Alias, Attribute, Class, Function, Object + from griffe.models import Alias, Attribute, Class, Function, Object POSITIONAL = frozenset((ParameterKind.positional_only, ParameterKind.positional_or_keyword)) KEYWORD = frozenset((ParameterKind.keyword_only, ParameterKind.positional_or_keyword)) diff --git a/src/_griffe/docstrings/google.py b/src/_griffe/docstrings/google.py index a36852d6..e0fa8efc 100644 --- a/src/_griffe/docstrings/google.py +++ b/src/_griffe/docstrings/google.py @@ -6,7 +6,7 @@ from contextlib import suppress from typing import TYPE_CHECKING, List, Tuple -from griffe.docstrings.dataclasses import ( +from griffe.docstrings.models import ( DocstringAttribute, DocstringClass, DocstringFunction, @@ -42,7 +42,7 @@ if TYPE_CHECKING: from typing import Any, Literal, Pattern - from griffe.dataclasses import Docstring + from griffe.models import Docstring from griffe.expressions import Expr _warn = warning(__name__) diff --git a/src/_griffe/docstrings/dataclasses.py b/src/_griffe/docstrings/models.py similarity index 99% rename from src/_griffe/docstrings/dataclasses.py rename to src/_griffe/docstrings/models.py index df29d682..8a969956 100644 --- a/src/_griffe/docstrings/dataclasses.py +++ b/src/_griffe/docstrings/models.py @@ -1,4 +1,4 @@ -"""This module contains the dataclasses related to docstrings.""" +"""This module contains the models related to docstrings.""" from __future__ import annotations diff --git a/src/_griffe/docstrings/numpy.py b/src/_griffe/docstrings/numpy.py index 4c2c902e..841188be 100644 --- a/src/_griffe/docstrings/numpy.py +++ b/src/_griffe/docstrings/numpy.py @@ -24,7 +24,7 @@ from textwrap import dedent from typing import TYPE_CHECKING -from griffe.docstrings.dataclasses import ( +from griffe.docstrings.models import ( DocstringAttribute, DocstringClass, DocstringFunction, @@ -60,7 +60,7 @@ if TYPE_CHECKING: from typing import Any, Literal, Pattern - from griffe.dataclasses import Docstring + from griffe.models import Docstring from griffe.expressions import Expr diff --git a/src/_griffe/docstrings/parsers.py b/src/_griffe/docstrings/parsers.py index 2a944da8..7739779c 100644 --- a/src/_griffe/docstrings/parsers.py +++ b/src/_griffe/docstrings/parsers.py @@ -4,14 +4,14 @@ from typing import TYPE_CHECKING, Any, Literal -from griffe.docstrings.dataclasses import DocstringSection, DocstringSectionText +from griffe.docstrings.models import DocstringSection, DocstringSectionText from griffe.docstrings.google import parse as parse_google from griffe.docstrings.numpy import parse as parse_numpy from griffe.docstrings.sphinx import parse as parse_sphinx from griffe.enumerations import Parser if TYPE_CHECKING: - from griffe.dataclasses import Docstring + from griffe.models import Docstring parsers = { Parser.google: parse_google, diff --git a/src/_griffe/docstrings/sphinx.py b/src/_griffe/docstrings/sphinx.py index 65120a0e..d1524d00 100644 --- a/src/_griffe/docstrings/sphinx.py +++ b/src/_griffe/docstrings/sphinx.py @@ -11,7 +11,7 @@ from dataclasses import dataclass, field from typing import TYPE_CHECKING, Any, Callable -from griffe.docstrings.dataclasses import ( +from griffe.docstrings.models import ( DocstringAttribute, DocstringParameter, DocstringRaise, @@ -26,7 +26,7 @@ from griffe.docstrings.utils import warning if TYPE_CHECKING: - from griffe.dataclasses import Docstring + from griffe.models import Docstring from griffe.expressions import Expr _warn = warning(__name__) diff --git a/src/_griffe/docstrings/utils.py b/src/_griffe/docstrings/utils.py index 63ba0698..654bf9ed 100644 --- a/src/_griffe/docstrings/utils.py +++ b/src/_griffe/docstrings/utils.py @@ -11,7 +11,7 @@ from griffe.logger import LogLevel, get_logger if TYPE_CHECKING: - from griffe.dataclasses import Docstring + from griffe.models import Docstring from griffe.expressions import Expr diff --git a/src/_griffe/encoders.py b/src/_griffe/encoders.py index e99fc1d4..985fe697 100644 --- a/src/_griffe/encoders.py +++ b/src/_griffe/encoders.py @@ -13,7 +13,7 @@ from typing import TYPE_CHECKING, Any, Callable from griffe import expressions -from griffe.dataclasses import ( +from griffe.models import ( Alias, Attribute, Class, diff --git a/src/_griffe/exceptions.py b/src/_griffe/exceptions.py index 41dff803..7b19a353 100644 --- a/src/_griffe/exceptions.py +++ b/src/_griffe/exceptions.py @@ -5,7 +5,7 @@ from typing import TYPE_CHECKING if TYPE_CHECKING: - from griffe.dataclasses import Alias + from griffe.models import Alias class GriffeError(Exception): diff --git a/src/_griffe/expressions.py b/src/_griffe/expressions.py index c03d0a96..b559cbf0 100644 --- a/src/_griffe/expressions.py +++ b/src/_griffe/expressions.py @@ -18,7 +18,7 @@ if TYPE_CHECKING: from pathlib import Path - from griffe.dataclasses import Class, Module + from griffe.models import Class, Module logger = get_logger(__name__) diff --git a/src/_griffe/extensions/base.py b/src/_griffe/extensions/base.py index c6b1cf79..72274af7 100644 --- a/src/_griffe/extensions/base.py +++ b/src/_griffe/extensions/base.py @@ -23,7 +23,7 @@ from griffe.agents.inspector import Inspector from griffe.agents.nodes import ObjectNode from griffe.agents.visitor import Visitor - from griffe.dataclasses import Attribute, Class, Function, Module, Object + from griffe.models import Attribute, Class, Function, Module, Object class VisitorExtension: diff --git a/src/_griffe/extensions/dataclasses.py b/src/_griffe/extensions/dataclasses.py index 70e53711..02196d6d 100644 --- a/src/_griffe/extensions/dataclasses.py +++ b/src/_griffe/extensions/dataclasses.py @@ -11,7 +11,7 @@ from functools import lru_cache from typing import Any, cast -from griffe.dataclasses import Attribute, Class, Decorator, Function, Module, Parameter, Parameters +from griffe.models import Attribute, Class, Decorator, Function, Module, Parameter, Parameters from griffe.enumerations import ParameterKind from griffe.expressions import ( Expr, diff --git a/src/_griffe/finder.py b/src/_griffe/finder.py index 1eb66dc2..b3db02bc 100644 --- a/src/_griffe/finder.py +++ b/src/_griffe/finder.py @@ -30,7 +30,7 @@ if TYPE_CHECKING: from typing import Pattern - from griffe.dataclasses import Module + from griffe.models import Module NamePartsType = Tuple[str, ...] diff --git a/src/_griffe/loader.py b/src/_griffe/loader.py index 52cd5523..d0bc27f5 100644 --- a/src/_griffe/loader.py +++ b/src/_griffe/loader.py @@ -22,7 +22,7 @@ from griffe.agents.inspector import inspect from griffe.agents.visitor import visit from griffe.collections import LinesCollection, ModulesCollection -from griffe.dataclasses import Alias, Module, Object +from griffe.models import Alias, Module, Object from griffe.enumerations import Kind from griffe.exceptions import AliasResolutionError, CyclicAliasError, LoadingError, UnimportableModuleError from griffe.expressions import ExprName @@ -138,10 +138,10 @@ def load( with regular methods and properties (`parent`, `members`, etc.). Examples: - >>> loader.load("griffe.dataclasses.Module") + >>> loader.load("griffe.models.Module") Class("Module") - >>> loader.load("src/griffe/dataclasses.py") - Module("dataclasses") + >>> loader.load("src/griffe/models.py") + Module("models") Parameters: objspec: The Python path of an object, or file path to a module. diff --git a/src/_griffe/merger.py b/src/_griffe/merger.py index 519d1ed8..7bd96e0d 100644 --- a/src/_griffe/merger.py +++ b/src/_griffe/merger.py @@ -9,7 +9,7 @@ from griffe.logger import get_logger if TYPE_CHECKING: - from griffe.dataclasses import Attribute, Class, Function, Module, Object + from griffe.models import Attribute, Class, Function, Module, Object logger = get_logger(__name__) diff --git a/src/_griffe/mixins.py b/src/_griffe/mixins.py index 91006b5d..dcea71d8 100644 --- a/src/_griffe/mixins.py +++ b/src/_griffe/mixins.py @@ -13,7 +13,7 @@ from griffe.merger import merge_stubs if TYPE_CHECKING: - from griffe.dataclasses import Alias, Attribute, Class, Function, Module, Object + from griffe.models import Alias, Attribute, Class, Function, Module, Object logger = get_logger(__name__) _ObjType = TypeVar("_ObjType") diff --git a/src/_griffe/dataclasses.py b/src/_griffe/models.py similarity index 98% rename from src/_griffe/dataclasses.py rename to src/_griffe/models.py index 22ddf24e..e0e1b1b0 100644 --- a/src/_griffe/dataclasses.py +++ b/src/_griffe/models.py @@ -24,7 +24,7 @@ if TYPE_CHECKING: from griffe.collections import LinesCollection, ModulesCollection - from griffe.docstrings.dataclasses import DocstringSection + from griffe.docstrings.models import DocstringSection from griffe.expressions import Expr from functools import cached_property @@ -433,7 +433,7 @@ def has_docstrings(self) -> bool: return any(member.has_docstrings for member in self.members.values()) def member_is_exported(self, member: Object | Alias, *, explicitely: bool = True) -> bool: # noqa: ARG002 - """Deprecated. Use [`member.is_exported`][griffe.dataclasses.Object.is_exported] instead.""" + """Deprecated. Use [`member.is_exported`][griffe.models.Object.is_exported] instead.""" warnings.warn( "Method `member_is_exported` is deprecated. Use `member.is_exported` instead.", DeprecationWarning, @@ -811,7 +811,7 @@ class Alias(ObjectAliasMixin): - the path is the alias path, not the canonical one - the name can be different from the target's - if the target can be resolved, the kind is the target's kind - - if the target cannot be resolved, the kind becomes [Kind.ALIAS][griffe.dataclasses.Kind] + - if the target cannot be resolved, the kind becomes [Kind.ALIAS][griffe.models.Kind] """ is_alias: bool = True @@ -1051,7 +1051,7 @@ def aliases(self) -> dict[str, Alias]: return self.final_target.aliases def member_is_exported(self, member: Object | Alias, *, explicitely: bool = True) -> bool: # noqa: ARG002 - """Deprecated. Use [`member.is_exported`][griffe.dataclasses.Alias.is_exported] instead.""" + """Deprecated. Use [`member.is_exported`][griffe.models.Alias.is_exported] instead.""" warnings.warn( "Method `member_is_exported` is deprecated. Use `member.is_exported` instead.", DeprecationWarning, @@ -1461,9 +1461,9 @@ def __init__(self, *args: Any, filepath: Path | list[Path] | None = None, **kwar """Initialize the module. Parameters: - *args: See [`griffe.dataclasses.Object`][]. + *args: See [`griffe.models.Object`][]. filepath: The module file path (directory for namespace [sub]packages, none for builtin modules). - **kwargs: See [`griffe.dataclasses.Object`][]. + **kwargs: See [`griffe.models.Object`][]. """ super().__init__(*args, **kwargs) self._filepath: Path | list[Path] | None = filepath @@ -1572,10 +1572,10 @@ def __init__( """Initialize the class. Parameters: - *args: See [`griffe.dataclasses.Object`][]. + *args: See [`griffe.models.Object`][]. bases: The list of base classes, if any. decorators: The class decorators, if any. - **kwargs: See [`griffe.dataclasses.Object`][]. + **kwargs: See [`griffe.models.Object`][]. """ super().__init__(*args, **kwargs) self.bases: list[Expr | str] = list(bases) if bases else [] @@ -1664,11 +1664,11 @@ def __init__( """Initialize the function. Parameters: - *args: See [`griffe.dataclasses.Object`][]. + *args: See [`griffe.models.Object`][]. parameters: The function parameters. returns: The function return annotation. decorators: The function decorators, if any. - **kwargs: See [`griffe.dataclasses.Object`][]. + **kwargs: See [`griffe.models.Object`][]. """ super().__init__(*args, **kwargs) self.parameters: Parameters = parameters or Parameters() @@ -1723,10 +1723,10 @@ def __init__( """Initialize the function. Parameters: - *args: See [`griffe.dataclasses.Object`][]. + *args: See [`griffe.models.Object`][]. value: The attribute value, if any. annotation: The attribute annotation, if any. - **kwargs: See [`griffe.dataclasses.Object`][]. + **kwargs: See [`griffe.models.Object`][]. """ super().__init__(*args, **kwargs) self.value: str | Expr | None = value diff --git a/src/_griffe/stats.py b/src/_griffe/stats.py index 116f80be..19931fec 100644 --- a/src/_griffe/stats.py +++ b/src/_griffe/stats.py @@ -10,7 +10,7 @@ from griffe.enumerations import Kind if TYPE_CHECKING: - from griffe.dataclasses import Alias, Object + from griffe.models import Alias, Object from griffe.loader import GriffeLoader diff --git a/src/_griffe/tests.py b/src/_griffe/tests.py index 75d07975..ef64f76a 100644 --- a/src/_griffe/tests.py +++ b/src/_griffe/tests.py @@ -14,7 +14,7 @@ from griffe.agents.inspector import inspect from griffe.agents.visitor import visit from griffe.collections import LinesCollection -from griffe.dataclasses import Module, Object +from griffe.models import Module, Object from griffe.loader import GriffeLoader if TYPE_CHECKING: diff --git a/tests/test_dataclasses.py b/tests/test_dataclasses.py index 9c0e3b98..43f4ea83 100644 --- a/tests/test_dataclasses.py +++ b/tests/test_dataclasses.py @@ -1,4 +1,4 @@ -"""Tests for the `dataclasses` module.""" +"""Tests for the `models` module.""" from __future__ import annotations @@ -8,7 +8,7 @@ import pytest import griffe -from griffe.dataclasses import Attribute, Docstring, Module +from griffe.models import Attribute, Docstring, Module from griffe.loader import GriffeLoader from griffe.tests import module_vtree, temporary_inspected_module, temporary_pypackage, temporary_visited_package @@ -78,12 +78,12 @@ def test_deepcopy() -> None: def test_alias_proxies() -> None: """Assert that the Alias class has all the necessary methods and properties.""" api = griffe.load("griffe") - alias_members = set(api["dataclasses.Alias"].all_members.keys()) + alias_members = set(api["models.Alias"].all_members.keys()) for cls in ( - api["dataclasses.Module"], - api["dataclasses.Class"], - api["dataclasses.Function"], - api["dataclasses.Attribute"], + api["models.Module"], + api["models.Class"], + api["models.Function"], + api["models.Attribute"], ): for name in cls.all_members: if not name.startswith("_") or name.startswith("__"): diff --git a/tests/test_docstrings/helpers.py b/tests/test_docstrings/helpers.py index 4a29bea0..cc83e95f 100644 --- a/tests/test_docstrings/helpers.py +++ b/tests/test_docstrings/helpers.py @@ -4,8 +4,8 @@ from typing import TYPE_CHECKING, Any, Iterator, List, Protocol, Tuple, Union -from griffe.dataclasses import Attribute, Class, Docstring, Function, Module -from griffe.docstrings.dataclasses import DocstringAttribute, DocstringElement, DocstringParameter, DocstringSection +from griffe.models import Attribute, Class, Docstring, Function, Module +from griffe.docstrings.models import DocstringAttribute, DocstringElement, DocstringParameter, DocstringSection from griffe.logger import LogLevel if TYPE_CHECKING: diff --git a/tests/test_docstrings/test_google.py b/tests/test_docstrings/test_google.py index bdc794b9..8cbcb62e 100644 --- a/tests/test_docstrings/test_google.py +++ b/tests/test_docstrings/test_google.py @@ -7,8 +7,8 @@ import pytest -from griffe.dataclasses import Attribute, Class, Docstring, Function, Module, Parameter, Parameters -from griffe.docstrings.dataclasses import DocstringReturn, DocstringSectionKind +from griffe.models import Attribute, Class, Docstring, Function, Module, Parameter, Parameters +from griffe.docstrings.models import DocstringReturn, DocstringSectionKind from griffe.docstrings.utils import parse_annotation from griffe.expressions import ExprName diff --git a/tests/test_docstrings/test_numpy.py b/tests/test_docstrings/test_numpy.py index 97fcf181..6107179e 100644 --- a/tests/test_docstrings/test_numpy.py +++ b/tests/test_docstrings/test_numpy.py @@ -7,8 +7,8 @@ import pytest -from griffe.dataclasses import Attribute, Class, Docstring, Function, Module, Parameter, Parameters -from griffe.docstrings.dataclasses import ( +from griffe.models import Attribute, Class, Docstring, Function, Module, Parameter, Parameters +from griffe.docstrings.models import ( DocstringSectionKind, ) from griffe.docstrings.utils import parse_annotation diff --git a/tests/test_docstrings/test_sphinx.py b/tests/test_docstrings/test_sphinx.py index eb84be13..572e8f9c 100644 --- a/tests/test_docstrings/test_sphinx.py +++ b/tests/test_docstrings/test_sphinx.py @@ -7,8 +7,8 @@ import pytest -from griffe.dataclasses import Attribute, Class, Function, Module, Parameter, Parameters -from griffe.docstrings.dataclasses import ( +from griffe.models import Attribute, Class, Function, Module, Parameter, Parameters +from griffe.docstrings.models import ( DocstringAttribute, DocstringParameter, DocstringRaise, diff --git a/tests/test_docstrings/test_warnings.py b/tests/test_docstrings/test_warnings.py index f9dba783..4b8d0713 100644 --- a/tests/test_docstrings/test_warnings.py +++ b/tests/test_docstrings/test_warnings.py @@ -2,7 +2,7 @@ from __future__ import annotations -from griffe.dataclasses import Docstring, Function, Parameter, ParameterKind, Parameters +from griffe.models import Docstring, Function, Parameter, ParameterKind, Parameters from griffe.docstrings.parsers import Parser, parse diff --git a/tests/test_encoders.py b/tests/test_encoders.py index 1f62478f..2331ca68 100644 --- a/tests/test_encoders.py +++ b/tests/test_encoders.py @@ -7,7 +7,7 @@ import pytest from jsonschema import ValidationError, validate -from griffe.dataclasses import Function, Module, Object +from griffe.models import Function, Module, Object from griffe.loader import GriffeLoader diff --git a/tests/test_expressions.py b/tests/test_expressions.py index 6828ec35..276d9b46 100644 --- a/tests/test_expressions.py +++ b/tests/test_expressions.py @@ -6,7 +6,7 @@ import pytest -from griffe.dataclasses import Module +from griffe.models import Module from griffe.docstrings.parsers import Parser from griffe.expressions import get_expression from griffe.tests import temporary_visited_module diff --git a/tests/test_extensions.py b/tests/test_extensions.py index 1949e393..772c17be 100644 --- a/tests/test_extensions.py +++ b/tests/test_extensions.py @@ -14,7 +14,7 @@ import ast from griffe.agents.nodes import ObjectNode - from griffe.dataclasses import Attribute, Class, Function, Module, Object + from griffe.models import Attribute, Class, Function, Module, Object class ExtensionTest(Extension): # noqa: D101 diff --git a/tests/test_finder.py b/tests/test_finder.py index 974f5d7f..cc347366 100644 --- a/tests/test_finder.py +++ b/tests/test_finder.py @@ -8,7 +8,7 @@ import pytest -from griffe.dataclasses import Module +from griffe.models import Module from griffe.finder import ModuleFinder, NamespacePackage, Package, _handle_editable_module, _handle_pth_file from griffe.tests import temporary_pypackage diff --git a/tests/test_functions.py b/tests/test_functions.py index 5f1e431f..a33398af 100644 --- a/tests/test_functions.py +++ b/tests/test_functions.py @@ -4,7 +4,7 @@ import pytest -from griffe.dataclasses import ParameterKind +from griffe.models import ParameterKind from griffe.tests import temporary_visited_module diff --git a/tests/test_git.py b/tests/test_git.py index e1b4daa8..e6a2c0ee 100644 --- a/tests/test_git.py +++ b/tests/test_git.py @@ -9,7 +9,7 @@ import pytest from griffe.cli import check -from griffe.dataclasses import Module +from griffe.models import Module from griffe.loader import load_git from tests import FIXTURES_DIR diff --git a/tests/test_inheritance.py b/tests/test_inheritance.py index 3206100e..bb93f240 100644 --- a/tests/test_inheritance.py +++ b/tests/test_inheritance.py @@ -10,7 +10,7 @@ from griffe.tests import temporary_inspected_module, temporary_visited_module if TYPE_CHECKING: - from griffe.dataclasses import Class + from griffe.models import Class def _mro_paths(cls: Class) -> list[str]: diff --git a/tests/test_loader.py b/tests/test_loader.py index 172d5b47..6f4d8d2e 100644 --- a/tests/test_loader.py +++ b/tests/test_loader.py @@ -16,7 +16,7 @@ if TYPE_CHECKING: from pathlib import Path - from griffe.dataclasses import Alias + from griffe.models import Alias def test_has_docstrings_does_not_try_to_resolve_alias() -> None: diff --git a/tests/test_stdlib.py b/tests/test_stdlib.py index 775711aa..08e3b2b9 100644 --- a/tests/test_stdlib.py +++ b/tests/test_stdlib.py @@ -12,7 +12,7 @@ from griffe.loader import GriffeLoader if TYPE_CHECKING: - from griffe.dataclasses import Alias, Object + from griffe.models import Alias, Object def _access_inherited_members(obj: Object | Alias) -> None: