on_node eventon_module_node event"}}
create_mod{{create module instance}}
event_mod_instance{{"on_instance eventon_module_instance event"}}
visit_mod_members{{visit module members}}
visit_cls{{enter class node}}
event_cls_node{{"on_node eventon_class_node event"}}
create_cls{{create class instance}}
event_cls_instance{{"on_instance eventon_class_instance event"}}
visit_cls_members{{visit class members}}
visit_func{{enter func node}}
event_func_node{{"on_node eventon_function_node event"}}
create_func{{create function instance}}
event_func_instance{{"on_instance eventon_function_instance event"}}
event_cls_members{{"on_members eventon_class_members event"}}
event_mod_members{{"on_members eventon_module_members event"}}
start{start} --> visit_mod
visit_mod --> event_mod_node
event_mod_node --> create_mod
create_mod --> event_mod_instance
event_mod_instance --> visit_mod_members
visit_mod_members --1--> visit_cls
visit_cls --> event_cls_node
event_cls_node --> create_cls
create_cls --> event_cls_instance
event_cls_instance --> visit_cls_members
visit_cls_members --1--> visit_func
visit_func --> event_func_node
event_func_node --> create_func
create_func --> event_func_instance
event_func_instance --> visit_cls_members
visit_cls_members --2--> event_cls_members
event_cls_members --> visit_mod_members
visit_mod_members --2--> event_mod_members
event_mod_members --> finish{finish}
class event_mod_node event
class event_mod_instance event
class event_cls_node event
class event_cls_instance event
class event_func_node event
class event_func_instance event
class event_cls_members event
class event_mod_members event
classDef event stroke:#3cc,stroke-width:2
```
Hopefully this flowchart gave you a pretty good idea
of what happens when Griffe collects data from a Python module.
The next setion will explain in more details
the different events that are triggered,
and how to hook onto them in your extensions.
### Events and hooks
There are two kinds of events in Griffe:
**load events** and **analysis events**.
Load events are scoped to the Griffe loader.
Analysis events are scoped to the visitor and inspector agents
(triggered during static and dynamic analysis).
#### Load events
There is only one **load event**:
- [`on_package_loaded`][griffe.extensions.base.Extension.on_package_loaded]
This event is triggered when the loader has finished loading a package entirely,
i.e. when all its submodules were scanned and loaded.
This event can be hooked by extensions which require the whole package to be loaded,
to be able to navigate the object tree without raising lookup errors
or alias resolution errors.
#### Analysis events
There are 3 generic **analysis events**:
- [`on_node`][griffe.extensions.base.Extension.on_node]
- [`on_instance`][griffe.extensions.base.Extension.on_instance]
- [`on_members`][griffe.extensions.base.Extension.on_members]
There are also specific **analysis events** for each object kind:
- [`on_module_node`][griffe.extensions.base.Extension.on_module_node]
- [`on_module_instance`][griffe.extensions.base.Extension.on_module_instance]
- [`on_module_members`][griffe.extensions.base.Extension.on_module_members]
- [`on_class_node`][griffe.extensions.base.Extension.on_class_node]
- [`on_class_instance`][griffe.extensions.base.Extension.on_class_instance]
- [`on_class_members`][griffe.extensions.base.Extension.on_class_members]
- [`on_function_node`][griffe.extensions.base.Extension.on_function_node]
- [`on_function_instance`][griffe.extensions.base.Extension.on_function_instance]
- [`on_attribute_node`][griffe.extensions.base.Extension.on_attribute_node]
- [`on_attribute_instance`][griffe.extensions.base.Extension.on_attribute_instance]
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],
and added it as a member of its parent.
The "on members" events are triggered when the agent
just finished handling all the members of an object.
Functions and attributes do not have members,
so there are no "on members" event for these two kinds.
**Hooks** are methods that are called when a particular
event is triggered. To target a specific event,
the hook must be named after it.
**Extensions** are classes that inherit from
[Griffe's Extension base class][griffe.extensions.Extension]
and define some hooks as methods:
```python
import ast
from griffe import Extension, Object, ObjectNode
class MyExtension(Extension):
def on_instance(self, node: ast.AST | ObjectNode, obj: Object) -> None:
"""Do something with `node` and/or `obj`."""
```
Hooks are always defined as methods of a class inheriting from
[Extension][griffe.extensions.Extension], never as standalone functions.
Since hooks are declared in a class, feel free to also declare state variables
(or any other variable) in the `__init__` method:
```python
import ast
from griffe import Extension, Object, ObjectNode
class MyExtension(Extension):
def __init__(self) -> None:
super().__init__()
self.state_thingy = "initial stuff"
self.list_of_things = []
def on_instance(self, node: ast.AST | ObjectNode, obj: Object) -> None:
"""Do something with `node` and/or `obj`."""
```
### Static/dynamic support
Extensions can support both static and dynamic analysis of modules.
If a module is scanned statically, your extension hooks
will receive AST nodes (from the [ast][] module of the standard library).
If the module is scanned dynamically,
your extension hooks will receive [object nodes][griffe.ObjectNode].
To support static analysis, dynamic analysis, or both,
you can therefore check the type of the received node:
```python
import ast
from griffe import Extension, Object, ObjectNode
class MyExtension(Extension):
def on_instance(self, node: ast.AST | ObjectNode, obj: Object) -> None:
"""Do something with `node` and/or `obj`."""
if isinstance(node, ast.AST):
... # apply logic for static analysis
else:
... # apply logic for dynamic analysis
```
Since hooks also receive instantiated modules, classes, functions and attributes,
most of the time you will not need to use the `node` argument
other than for checking its type and deciding what to do based on the result.
If you do need to, read the next section explaining how to visit trees.
### Visiting trees
Extensions provide basic functionality to help you visit trees:
- [`visit`][griffe.extensions.base.Extension.visit]: call `self.visit(node)`
to start visiting an abstract syntax tree.
- [`generic_visit`][griffe.extensions.base.Extension.generic_visit]: call
`self.generic_visit(node)` to visit each subnode of a given node.
- [`inspect`][griffe.extensions.base.Extension.inspect]: call `self.inspect(node)`
to start visiting an object tree. Nodes contain references to the runtime objects,
see [`ObjectNode`][griffe.agents.nodes.ObjectNode].
- [`generic_inspect`][griffe.extensions.base.Extension.generic_inspect]: call
`self.generic_inspect(node)` to visit each subnode of a given node.
Calling `self.visit(node)` or `self.inspect(node)` will do nothing
unless you actually implement methods that handle specific types of nodes:
- for ASTs, methods must be named `visit_| > > - [`Add`][ast.Add] > - [`alias`][ast.alias] > - [`And`][ast.And] > - [`AnnAssign`][ast.AnnAssign] > - [`arg`][ast.arg] > - [`arguments`][ast.arguments] > - [`Assert`][ast.Assert] > - [`Assign`][ast.Assign] > - [`AsyncFor`][ast.AsyncFor] > - [`AsyncFunctionDef`][ast.AsyncFunctionDef] > - [`AsyncWith`][ast.AsyncWith] > - [`Attribute`][ast.Attribute] > - [`AugAssign`][ast.AugAssign] > - [`Await`][ast.Await] > - [`BinOp`][ast.BinOp] > - [`BitAnd`][ast.BitAnd] > - [`BitOr`][ast.BitOr] > - [`BitXor`][ast.BitXor] > - [`BoolOp`][ast.BoolOp] > - [`Break`][ast.Break] > - `Bytes`[^1] > - [`Call`][ast.Call] > - [`ClassDef`][ast.ClassDef] > - [`Compare`][ast.Compare] > - [`comprehension`][ast.comprehension] > - [`Constant`][ast.Constant] > - [`Continue`][ast.Continue] > - [`Del`][ast.Del] > - [`Delete`][ast.Delete] > > | > > - [`Dict`][ast.Dict] > - [`DictComp`][ast.DictComp] > - [`Div`][ast.Div] > - `Ellipsis`[^1] > - [`Eq`][ast.Eq] > - [`ExceptHandler`][ast.ExceptHandler] > - [`Expr`][ast.Expr] > - `Expression`[^1] > - `ExtSlice`[^2] > - [`FloorDiv`][ast.FloorDiv] > - [`For`][ast.For] > - [`FormattedValue`][ast.FormattedValue] > - [`FunctionDef`][ast.FunctionDef] > - [`GeneratorExp`][ast.GeneratorExp] > - [`Global`][ast.Global] > - [`Gt`][ast.Gt] > - [`GtE`][ast.GtE] > - [`If`][ast.If] > - [`IfExp`][ast.IfExp] > - [`Import`][ast.Import] > - [`ImportFrom`][ast.ImportFrom] > - [`In`][ast.In] > - `Index`[^2] > - `Interactive`[^3] > - [`Invert`][ast.Invert] > - [`Is`][ast.Is] > - [`IsNot`][ast.IsNot] > - [`JoinedStr`][ast.JoinedStr] > - [`keyword`][ast.keyword] > > | > > - [`Lambda`][ast.Lambda] > - [`List`][ast.List] > - [`ListComp`][ast.ListComp] > - [`Load`][ast.Load] > - [`LShift`][ast.LShift] > - [`Lt`][ast.Lt] > - [`LtE`][ast.LtE] > - [`Match`][ast.Match] > - [`MatchAs`][ast.MatchAs] > - [`match_case`][ast.match_case] > - [`MatchClass`][ast.MatchClass] > - [`MatchMapping`][ast.MatchMapping] > - [`MatchOr`][ast.MatchOr] > - [`MatchSequence`][ast.MatchSequence] > - [`MatchSingleton`][ast.MatchSingleton] > - [`MatchStar`][ast.MatchStar] > - [`MatchValue`][ast.MatchValue] > - [`MatMult`][ast.MatMult] > - [`Mod`][ast.Mod] > - `Module`[^3] > - [`Mult`][ast.Mult] > - [`Name`][ast.Name] > - `NameConstant`[^1] > - [`NamedExpr`][ast.NamedExpr] > - [`Nonlocal`][ast.Nonlocal] > - [`Not`][ast.Not] > - [`NotEq`][ast.NotEq] > - [`NotIn`][ast.NotIn] > - `Num`[^1] > > | > > - [`Or`][ast.Or] > - [`Pass`][ast.Pass] > - `pattern`[^3] > - [`Pow`][ast.Pow] > - `Print`[^4] > - [`Raise`][ast.Raise] > - [`Return`][ast.Return] > - [`RShift`][ast.RShift] > - [`Set`][ast.Set] > - [`SetComp`][ast.SetComp] > - [`Slice`][ast.Slice] > - [`Starred`][ast.Starred] > - [`Store`][ast.Store] > - `Str`[^1] > - [`Sub`][ast.Sub] > - [`Subscript`][ast.Subscript] > - [`Try`][ast.Try] > - `TryExcept`[^5] > - `TryFinally`[^6] > - [`Tuple`][ast.Tuple] > - [`UAdd`][ast.UAdd] > - [`UnaryOp`][ast.UnaryOp] > - [`USub`][ast.USub] > - [`While`][ast.While] > - [`With`][ast.With] > - [`withitem`][ast.withitem] > - [`Yield`][ast.Yield] > - [`YieldFrom`][ast.YieldFrom] > > |
{code}{code}'
sponsors.forEach(function (sponsor) {
html += `
`
});
html += '
If you sponsor publicly, you're automatically added here with a link to your profile and avatar to show your support for *griffe*. Alternatively, if you wish to keep your sponsorship private, you'll be a silent +1. You can select visibility during checkout and change it afterwards. ## Funding ### Goals The following section lists all funding goals. Each goal contains a list of features prefixed with a checkmark symbol, denoting whether a feature is :octicons-check-circle-fill-24:{ style="color: #00e676" } already available or :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features are released for general availability. ```python exec="1" session="insiders" idprefix="" for goal in goals.values(): if not goal.complete: goal.render() ``` ### Goals completed This section lists all funding goals that were previously completed, which means that those features were part of Insiders, but are now generally available and can be used by all users. ```python exec="1" session="insiders" for goal in goals.values(): if goal.complete: goal.render() ``` ## Frequently asked questions ### Compatibility > We're building an open source project and want to allow outside collaborators to use *griffe* locally without having access to Insiders. Is this still possible? Yes. Insiders is compatible with *griffe*. Almost all new features and configuration options are either backward-compatible or implemented behind feature flags. Most Insiders features enhance the overall experience, though while these features add value for the users of your project, they shouldn't be necessary for previewing when making changes to content. ### Payment > We don't want to pay for sponsorship every month. Are there any other options? Yes. You can sponsor on a yearly basis by [switching your GitHub account to a yearly billing cycle][billing cycle]. If for some reason you cannot do that, you could also create a dedicated GitHub account with a yearly billing cycle, which you only use for sponsoring (some sponsors already do that). If you have any problems or further questions, please reach out to pawamoy@pm.me. ### Terms > Are we allowed to use Insiders under the same terms and conditions as *griffe*? Yes. Whether you're an individual or a company, you may use *griffe Insiders* precisely under the same terms as *griffe*, which are given by the [ISC License][license]. However, we kindly ask you to respect our **fair use policy**: - Please **don't distribute the source code** of Insiders. You may freely use it for public, private or commercial projects, privately fork or mirror it, but please don't make the source code public, as it would counteract the sponsorware strategy. - If you cancel your subscription, you're automatically removed as a collaborator and will miss out on all future updates of Insiders. However, you may **use the latest version** that's available to you **as long as you like**. Just remember that [GitHub deletes private forks][private forks]. [insiders]: #what-is-insiders [sponsorship]: #what-sponsorships-achieve [sponsors]: #how-to-become-a-sponsor [features]: #whats-in-it-for-me [funding]: #funding [goals completed]: #goals-completed [github sponsor profile]: https://github.com/sponsors/pawamoy [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle [license]: ../license.md [private forks]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository python-griffe-0.40.0/docs/schema-docstrings-options.json 0000644 0001750 0001750 00000002070 14556223422 023171 0 ustar carsten carsten { "$schema": "https://json-schema.org/draft-07/schema", "title": "Griffe docstrings parsing options.", "type": "object", "properties": { "ignore_init_summary": { "title": "Whether to discard the summary line in `__init__` methods' docstrings.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/docstrings/google/#griffe.docstrings.google.parse", "type": "boolean", "default": false }, "trim_doctest_flags": { "title": "Whether to remove doctest flags from Python example blocks.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/docstrings/google/#griffe.docstrings.google.parse", "type": "boolean", "default": true }, "returns_multiple_items": { "title": "Whether the `Returns` section has multiple items.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/docstrings/google/#griffe.docstrings.google.parse", "type": "boolean", "default": true } }, "additionalProperties": false } python-griffe-0.40.0/docs/index.md 0000644 0001750 0001750 00000000023 14556223422 016615 0 ustar carsten carsten --8<-- "README.md" python-griffe-0.40.0/docs/schema.json 0000644 0001750 0001750 00000032475 14556223422 017337 0 ustar carsten carsten { "$schema": "http://json-schema.org/draft-07/schema", "title": "Griffe object.", "oneOf": [ { "type": "object", "properties": { "name": { "title": "The name of the alias.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.name", "type": "string" }, "kind": { "title": "The 'alias' kind.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Alias.kind", "const": "alias" }, "path": { "title": "The alias path.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.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", "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", "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", "type": [ "integer", "null" ] } }, "additionalProperties": false, "required": [ "name", "kind", "path", "target_path", "lineno" ] }, { "type": "object", "properties": { "name": { "title": "The name of the object.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.name", "type": "string" }, "kind": { "title": "The kind of object.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.kind", "enum": [ "module", "class", "function", "attribute" ] }, "path": { "title": "The path of the object (dot-separated Python path).", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.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", "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", "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", "type": "string" }, "labels": { "title": "The labels of the object.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Object.labels", "type": "array" }, "docstring": { "title": "The docstring of the object.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring", "type": "object", "properties": { "value": { "title": "The actual string.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.value", "type": "string" }, "lineno": { "title": "The docstring starting line number.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.lineno", "type": "integer" }, "endlineno": { "title": "The docstring ending line number.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.endlineno", "type": [ "integer", "null" ] }, "parsed": { "title": "The parsed docstring (list of docstring sections).", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.parsed", "type": "array", "items": { "type": "object", "properties": { "kind": { "title": "The docstring section kind.", "enum": [ "text", "parameters", "other parameters", "raises", "warns", "returns", "yields", "receives", "examples", "attributes", "deprecated", "admonition" ] }, "value": { "title": "The docstring section value", "type": [ "string", "array" ] } }, "required": [ "kind", "value" ] } } }, "required": [ "value", "lineno", "endlineno" ] }, "members": { "type": "array", "items": { "$ref": "#" } }, "lineno": { "title": "The docstring starting line number.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.lineno", "type": "integer" }, "endlineno": { "title": "The docstring ending line number.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Docstring.endlineno", "type": [ "integer", "null" ] }, "bases": true, "decorators": true, "parameters": true, "returns": true, "value": true, "annotation": true }, "additionalProperties": false, "required": [ "name", "kind", "path", "filepath", "relative_filepath", "relative_package_filepath", "labels", "members" ], "allOf": [ { "if": { "properties": { "kind": { "const": "class" } } }, "then": { "properties": { "bases": { "title": "For classes, their bases classes.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Class.bases", "type": "array", "items": { "$ref": "#/$defs/annotation" } }, "decorators": { "title": "For classes, their decorators.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.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", "$ref": "#/$defs/annotation" }, "lineno": { "title": "The decorator starting line number.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Decorator.lineno", "type": "integer" }, "endlineno": { "title": "The decorator ending line number.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Decorator.endlineno", "type": [ "integer", "null" ] } }, "additionalProperties": false, "required": [ "value", "lineno", "endlineno" ] } } }, "required": [ "bases", "decorators" ] } }, { "if": { "properties": { "kind": { "const": "function" } } }, "then": { "properties": { "parameters": { "title": "For functions, their parameters.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.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", "type": "string" }, "annotation": { "title": "The annotation of the parameter.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Parameter.annotation", "$ref": "#/$defs/annotation" }, "kind": { "title": "The kind of parameter.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.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", "$ref": "#/$defs/annotation" } }, "required": [ "name", "kind" ] } }, "returns": { "title": "For functions, their return annotation.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.Function.returns", "$ref": "#/$defs/annotation" } }, "required": [ "parameters", "returns" ] } }, { "if": { "properties": { "kind": { "const": "attribute" } } }, "then": { "properties": { "value": { "title": "For attributes, their value.", "markdownDescription": "https://mkdocstrings.github.io/griffe/reference/griffe/dataclasses/#griffe.dataclasses.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", "$ref": "#/$defs/annotation" } } } } ] } ], "$defs": { "expression": { "type": "object", "additionalProperties": true }, "annotation": { "oneOf": [ { "type": "null" }, { "type": "string" }, { "$ref": "#/$defs/expression" } ] } } } python-griffe-0.40.0/README.md 0000644 0001750 0001750 00000010642 14556223422 015523 0 ustar carsten carsten # Griffe [](https://github.com/mkdocstrings/griffe/actions?query=workflow%3Aci) [](https://mkdocstrings.github.io/griffe/) [](https://pypi.org/project/griffe/) [](https://gitpod.io/#https://github.com/mkdocstrings/griffe) [](https://app.gitter.im/#/room/#mkdocstrings_griffe:gitter.im)
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.
Griffe, pronounced "grif" (`/ɡʁif/`), is a french word that means "claw",
but also "signature" in a familiar way. "On reconnaît bien là sa griffe."
## Installation
With `pip`:
```bash
pip install griffe
```
With [`pipx`](https://github.com/pipxproject/pipx):
```bash
python3.8 -m pip install --user pipx
pipx install griffe
```
## Usage
**On the command line**, pass the names of packages to the `griffe dump` command:
```console
$ griffe dump httpx fastapi
{
"httpx": {
"name": "httpx",
...
},
"fastapi": {
"name": "fastapi",
...
}
}
```
See [the Dumping data section](https://mkdocstrings.github.io/griffe/dumping/) for more examples.
Or pass a relative path to the `griffe check` command:
```console
$ griffe check mypackage --verbose
mypackage/mymodule.py:10: MyClass.mymethod(myparam):
Parameter kind was changed:
Old: positional or keyword
New: keyword-only
```
For `src` layouts:
```console
$ griffe check --search src mypackage --verbose
src/mypackage/mymodule.py:10: MyClass.mymethod(myparam):
Parameter kind was changed:
Old: positional or keyword
New: keyword-only
```
See [the API breakage section](https://mkdocstrings.github.io/griffe/checking/) for more examples.
**With Python**, loading a package:
```python
import griffe
fastapi = griffe.load("fastapi")
```
Finding breaking changes:
```python
import griffe
previous = griffe.load_git("mypackage", ref="0.2.0")
current = griffe.load("mypackage")
for breakage in griffe.find_breaking_changes(previous, current):
...
```
See [the Loading data section](https://mkdocstrings.github.io/griffe/loading/) for more examples.
## Todo
- Extensions
- Post-processing extensions
- Third-party libraries we could provide support for:
- Django support
- Marshmallow support
- Pydantic support
- Docstrings parsers
- epydoc
- New Markdown-based format? For graceful degradation
- Serializer:
- Flat JSON
- API diff:
- [ ] Mechanism to cache APIs? Should users version them, or store them somewhere (docs)?
- [ ] Ability to return warnings (things that are not backward-compatibility-friendly)
- List of things to consider for warnings
- Multiple positional-or-keyword parameters
- Public imports in public modules
- Private things made public through imports/assignments
- Too many public things? Generally annoying. Configuration?
- [x] Ability to compare two APIs to return breaking changes
- List of things to consider for breaking changes
- [x] Changed position of positional only parameter
- [x] Changed position of positional or keyword parameter
- [ ] Changed type of parameter
- [ ] Changed type of public module attribute
- [ ] Changed return type of a public function/method
- [x] Added parameter without a default value
- [x] Removed keyword-only parameter without a default value, without **kwargs to swallow it
- [x] Removed positional-only parameter without a default value, without *args to swallow it
- [x] Removed positional-or_keyword argument without a default value, without *args and **kwargs to swallow it
- [x] Removed public module/class/function/method/attribute
- [ ] All of the previous even when parent is private (could be publicly imported or assigned somewhere),
and later be smarter: public assign/import makes private things public!
- [ ] Inheritance: removed, added or changed base that changes MRO
python-griffe-0.40.0/.gitpod.dockerfile 0000644 0001750 0001750 00000000174 14556223422 017640 0 ustar carsten carsten FROM gitpod/workspace-full
USER gitpod
ENV PIP_USER=no
RUN pip3 install pipx; \
pipx install pdm; \
pipx ensurepath
python-griffe-0.40.0/Makefile 0000644 0001750 0001750 00000002024 14556223422 015677 0 ustar carsten carsten .DEFAULT_GOAL := help
SHELL := bash
DUTY := $(if $(VIRTUAL_ENV),,pdm run) duty
export PDM_MULTIRUN_VERSIONS ?= 3.8 3.9 3.10 3.11 3.12
export PDM_MULTIRUN_USE_VENVS ?= $(if $(shell pdm config python.use_venv | grep True),1,0)
args = $(foreach a,$($(subst -,_,$1)_args),$(if $(value $a),$a="$($a)"))
check_quality_args = files
docs_args = host port
release_args = version
test_args = match
fuzz_args = seeds min_seed max_seed size
BASIC_DUTIES = \
changelog \
check-api \
check-dependencies \
clean \
coverage \
docs \
docs-deploy \
format \
release \
fuzz \
vscode
QUALITY_DUTIES = \
check-quality \
check-docs \
check-types \
test
.PHONY: help
help:
@$(DUTY) --list
.PHONY: lock
lock:
@pdm lock -G:all
.PHONY: setup
setup:
@bash scripts/setup.sh
.PHONY: check
check:
@pdm multirun duty check-quality check-types check-docs
@$(DUTY) check-dependencies check-api
.PHONY: $(BASIC_DUTIES)
$(BASIC_DUTIES):
@$(DUTY) $@ $(call args,$@)
.PHONY: $(QUALITY_DUTIES)
$(QUALITY_DUTIES):
@pdm multirun duty $@ $(call args,$@)
python-griffe-0.40.0/.gitignore 0000644 0001750 0001750 00000000375 14556223422 016236 0 ustar carsten carsten .idea/
__pycache__/
*.py[cod]
dist/
*.egg-info/
build/
htmlcov/
.coverage*
pip-wheel-metadata/
.pytest_cache/
.mypy_cache/
site/
pdm.lock
pdm.toml
.pdm-plugins/
.pdm-python
__pypackages__/
.venv/
.cache/
profile.pstats
profile.svg
.hypothesis/
.vscode/
python-griffe-0.40.0/duties.py 0000644 0001750 0001750 00000026066 14556223422 016122 0 ustar carsten carsten """Development tasks."""
from __future__ import annotations
import os
import sys
from contextlib import contextmanager
from importlib.metadata import version as pkgversion
from pathlib import Path
from typing import TYPE_CHECKING, Iterator
from duty import duty
from duty.callables import black, coverage, lazy, mkdocs, mypy, pytest, ruff, safety
if TYPE_CHECKING:
from duty.context import Context
PY_SRC_PATHS = (Path(_) for _ in ("src", "tests", "duties.py", "scripts"))
PY_SRC_LIST = tuple(str(_) for _ in PY_SRC_PATHS)
PY_SRC = " ".join(PY_SRC_LIST)
CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""}
WINDOWS = os.name == "nt"
PTY = not WINDOWS and not CI
MULTIRUN = os.environ.get("PDM_MULTIRUN", "0") == "1"
def pyprefix(title: str) -> str: # noqa: D103
if MULTIRUN:
prefix = f"(python{sys.version_info.major}.{sys.version_info.minor})"
return f"{prefix:14}{title}"
return title
@contextmanager
def material_insiders() -> Iterator[bool]: # noqa: D103
if "+insiders" in pkgversion("mkdocs-material"):
os.environ["MATERIAL_INSIDERS"] = "true"
try:
yield True
finally:
os.environ.pop("MATERIAL_INSIDERS")
else:
yield False
@duty
def changelog(ctx: Context) -> None:
"""Update the changelog in-place with latest commits.
Parameters:
ctx: The context instance (passed automatically).
"""
from git_changelog.cli import main as git_changelog
ctx.run(git_changelog, args=[[]], title="Updating changelog")
@duty(pre=["check_quality", "check_types", "check_docs", "check_dependencies", "check-api"])
def check(ctx: Context) -> None: # noqa: ARG001
"""Check it all!
Parameters:
ctx: The context instance (passed automatically).
"""
@duty
def check_quality(ctx: Context) -> None:
"""Check the code quality.
Parameters:
ctx: The context instance (passed automatically).
"""
ctx.run(
ruff.check(*PY_SRC_LIST, config="config/ruff.toml"),
title=pyprefix("Checking code quality"),
command=f"ruff check --config config/ruff.toml {PY_SRC}",
)
@duty
def check_dependencies(ctx: Context) -> None:
"""Check for vulnerabilities in dependencies.
Parameters:
ctx: The context instance (passed automatically).
"""
# retrieve the list of dependencies
requirements = ctx.run(
["pdm", "export", "-f", "requirements", "--without-hashes"],
title="Exporting dependencies as requirements",
allow_overrides=False,
)
ctx.run(
safety.check(requirements),
title="Checking dependencies",
command="pdm export -f requirements --without-hashes | safety check --stdin",
)
@duty
def check_docs(ctx: Context) -> None:
"""Check if the documentation builds correctly.
Parameters:
ctx: The context instance (passed automatically).
"""
Path("htmlcov").mkdir(parents=True, exist_ok=True)
Path("htmlcov/index.html").touch(exist_ok=True)
with material_insiders():
ctx.run(
mkdocs.build(strict=True, verbose=True),
title=pyprefix("Building documentation"),
command="mkdocs build -vs",
)
@duty
def check_types(ctx: Context) -> None:
"""Check that the code is correctly typed.
Parameters:
ctx: The context instance (passed automatically).
"""
ctx.run(
mypy.run(*PY_SRC_LIST, config_file="config/mypy.ini"),
title=pyprefix("Type-checking"),
command=f"mypy --config-file config/mypy.ini {PY_SRC}",
)
@duty
def check_api(ctx: Context) -> None:
"""Check for API breaking changes.
Parameters:
ctx: The context instance (passed automatically).
"""
from griffe.cli import check as g_check
griffe_check = lazy(g_check, name="griffe.check")
ctx.run(
griffe_check("griffe", search_paths=["src"], color=True),
title="Checking for API breaking changes",
command="griffe check -ssrc griffe",
nofail=True,
)
@duty(silent=True)
def clean(ctx: Context) -> None:
"""Delete temporary files.
Parameters:
ctx: The context instance (passed automatically).
"""
ctx.run("rm -rf .coverage*")
ctx.run("rm -rf .mypy_cache")
ctx.run("rm -rf .pytest_cache")
ctx.run("rm -rf tests/.pytest_cache")
ctx.run("rm -rf build")
ctx.run("rm -rf dist")
ctx.run("rm -rf htmlcov")
ctx.run("rm -rf pip-wheel-metadata")
ctx.run("rm -rf site")
ctx.run("find . -type d -name __pycache__ | xargs rm -rf")
ctx.run("find . -name '*.rej' -delete")
@duty
def docs(ctx: Context, host: str = "127.0.0.1", port: int = 8000) -> None:
"""Serve the documentation (localhost:8000).
Parameters:
ctx: The context instance (passed automatically).
host: The host to serve the docs from.
port: The port to serve the docs on.
"""
with material_insiders():
ctx.run(
mkdocs.serve(dev_addr=f"{host}:{port}"),
title="Serving documentation",
capture=False,
)
@duty
def docs_deploy(ctx: Context) -> None:
"""Deploy the documentation on GitHub pages.
Parameters:
ctx: The context instance (passed automatically).
"""
os.environ["DEPLOY"] = "true"
with material_insiders() as insiders:
if not insiders:
ctx.run(lambda: False, title="Not deploying docs without Material for MkDocs Insiders!")
origin = ctx.run("git config --get remote.origin.url", silent=True)
if "pawamoy-insiders/griffe" in origin:
ctx.run("git remote add upstream git@github.com:mkdocstrings/griffe", silent=True, nofail=True)
ctx.run(
mkdocs.gh_deploy(remote_name="upstream", force=True),
title="Deploying documentation",
)
else:
ctx.run(
lambda: False,
title="Not deploying docs from public repository (do that from insiders instead!)",
nofail=True,
)
@duty
def format(ctx: Context) -> None:
"""Run formatting tools on the code.
Parameters:
ctx: The context instance (passed automatically).
"""
ctx.run(
ruff.check(*PY_SRC_LIST, config="config/ruff.toml", fix_only=True, exit_zero=True),
title="Auto-fixing code",
)
ctx.run(black.run(*PY_SRC_LIST, config="config/black.toml"), title="Formatting code")
@duty(post=["docs-deploy"])
def release(ctx: Context, version: str) -> None:
"""Release a new Python package.
Parameters:
ctx: The context instance (passed automatically).
version: The new version number to use.
"""
origin = ctx.run("git config --get remote.origin.url", silent=True)
if "pawamoy-insiders/griffe" in origin:
ctx.run(
lambda: False,
title="Not releasing from insiders repository (do that from public repo instead!)",
)
ctx.run("git add pyproject.toml CHANGELOG.md", title="Staging files", pty=PTY)
ctx.run(["git", "commit", "-m", f"chore: Prepare release {version}"], title="Committing changes", pty=PTY)
ctx.run(f"git tag {version}", title="Tagging commit", pty=PTY)
ctx.run("git push", title="Pushing commits", pty=False)
ctx.run("git push --tags", title="Pushing tags", pty=False)
ctx.run("pdm build", title="Building dist/wheel", pty=PTY)
ctx.run("twine upload --skip-existing dist/*", title="Publishing version", pty=PTY)
@duty(silent=True, aliases=["coverage"])
def cov(ctx: Context) -> None:
"""Report coverage as text and HTML.
Parameters:
ctx: The context instance (passed automatically).
"""
ctx.run(coverage.combine, nofail=True)
ctx.run(coverage.report(rcfile="config/coverage.ini"), capture=False)
ctx.run(coverage.html(rcfile="config/coverage.ini"))
@duty
def test(ctx: Context, match: str = "") -> None:
"""Run the test suite.
Parameters:
ctx: The context instance (passed automatically).
match: A pytest expression to filter selected tests.
"""
py_version = f"{sys.version_info.major}{sys.version_info.minor}"
os.environ["COVERAGE_FILE"] = f".coverage.{py_version}"
ctx.run(
pytest.run("-n", "auto", "tests", config_file="config/pytest.ini", select=match, color="yes", verbosity=10),
title=pyprefix("Running tests"),
command=f"pytest -c config/pytest.ini -n auto -k{match!r} --color=yes tests",
)
class Seeds(list): # noqa: D101
def __init__(self, cli_value: str = "") -> None: # noqa: D107
if cli_value:
self.extend(int(seed) for seed in cli_value.split(","))
@duty
def fuzz(
ctx: Context,
*,
size: int = 20,
min_seed: int = 0,
max_seed: int = 1_000_000,
seeds: Seeds = Seeds(), # noqa: B008
) -> None:
"""Fuzz Griffe against generated Python code.
Parameters:
ctx: The context instance (passed automatically).
size: The size of the case set (number of cases to test).
seeds: Seeds to test or exclude.
min_seed: Minimum value for the seeds range.
max_seed: Maximum value for the seeds range.
"""
import warnings
from random import sample
from tempfile import gettempdir
from pysource_codegen import generate
from pysource_minimize import minimize
from griffe.agents.visitor import visit
warnings.simplefilter("ignore", SyntaxWarning)
def fails(code: str, filepath: Path) -> bool:
try:
visit(filepath.stem, filepath=filepath, code=code)
except Exception: # noqa: BLE001
return True
return False
def test_seed(seed: int, revisit: bool = False) -> bool: # noqa: FBT001,FBT002
filepath = Path(gettempdir(), f"fuzz_{seed}_{sys.version_info.minor}.py")
if filepath.exists():
if revisit:
code = filepath.read_text()
else:
return True
else:
code = generate(seed)
filepath.write_text(code)
if fails(code, filepath):
new_code = minimize(code, fails)
if code != new_code:
filepath.write_text(new_code)
return False
return True
revisit = bool(seeds)
seeds = seeds or sample(range(min_seed, max_seed + 1), size) # type: ignore[assignment]
for seed in seeds:
ctx.run(test_seed, args=[seed, revisit], title=f"Visiting code generated with seed {seed}")
@duty
def vscode(ctx: Context) -> None:
"""Configure VSCode.
This task will overwrite the following files,
so make sure to back them up:
- `.vscode/launch.json`
- `.vscode/settings.json`
- `.vscode/tasks.json`
Parameters:
ctx: The context instance (passed automatically).
"""
def update_config(filename: str) -> None:
source_file = Path("config", "vscode", filename)
target_file = Path(".vscode", filename)
target_file.parent.mkdir(exist_ok=True)
target_file.write_text(source_file.read_text())
for filename in ("launch.json", "settings.json", "tasks.json"):
ctx.run(update_config, args=[filename], title=f"Update .vscode/{filename}")
python-griffe-0.40.0/tests/ 0000755 0001750 0001750 00000000000 14556223422 015403 5 ustar carsten carsten python-griffe-0.40.0/tests/test_git.py 0000644 0001750 0001750 00000006711 14556223422 017604 0 ustar carsten carsten """Tests for creating a griffe Module from specific commits in a git repository."""
from __future__ import annotations
import shutil
from subprocess import run
from typing import TYPE_CHECKING
import pytest
from griffe.cli import check
from griffe.dataclasses import Module
from griffe.git import load_git
from tests import FIXTURES_DIR
if TYPE_CHECKING:
from pathlib import Path
REPO_NAME = "my-repo"
REPO_SOURCE = FIXTURES_DIR / "_repo"
MODULE_NAME = "my_module"
def _copy_contents(src: Path, dst: Path) -> None:
"""Copy *contents* of src into dst.
Parameters:
src: the folder whose contents will be copied to dst
dst: the destination folder
"""
dst.mkdir(exist_ok=True, parents=True)
for src_path in src.iterdir():
dst_path = dst / src_path.name
if src_path.is_dir():
_copy_contents(src_path, dst_path)
else:
shutil.copy(src_path, dst_path)
@pytest.fixture()
def git_repo(tmp_path: Path) -> Path:
"""Fixture that creates a git repo with multiple tagged versions.
For each directory in `tests/test_git/_repo/`
- the contents of the directory will be copied into the temporary repo
- all files will be added and commited
- the commit will be tagged with the name of the directory
To add to these tests (i.e. to simulate change over time), either modify one of
the files in the existing `v0.1.0`, `v0.2.0` folders, or continue adding new
version folders following the same pattern.
Parameters:
tmp_path: temporary directory fixture
Returns:
Path: path to temporary repo.
"""
repo_path = tmp_path / REPO_NAME
repo_path.mkdir()
run(["git", "-C", str(repo_path), "init"], check=True)
run(["git", "-C", str(repo_path), "config", "user.name", "Name"], check=True)
run(["git", "-C", str(repo_path), "config", "user.email", "my@email.com"], check=True)
for tagdir in REPO_SOURCE.iterdir():
ver = tagdir.name
_copy_contents(tagdir, repo_path)
run(["git", "-C", str(repo_path), "add", "."], check=True)
run(["git", "-C", str(repo_path), "commit", "-m", f"feat: {ver} stuff"], check=True)
run(["git", "-C", str(repo_path), "tag", ver], check=True)
return repo_path
def test_load_git(git_repo: Path) -> None:
"""Test that we can load modules from different commits from a git repo.
Parameters:
git_repo: temporary git repo
"""
v1 = load_git(MODULE_NAME, ref="v0.1.0", repo=git_repo)
v2 = load_git(MODULE_NAME, ref="v0.2.0", repo=git_repo)
assert isinstance(v1, Module)
assert isinstance(v2, Module)
assert v1.attributes["__version__"].value == "'0.1.0'"
assert v2.attributes["__version__"].value == "'0.2.0'"
def test_load_git_errors(git_repo: Path) -> None:
"""Test that we get informative errors for various invalid inputs.
Parameters:
git_repo: temporary git repo
"""
with pytest.raises(OSError, match="Not a git repository"):
load_git(MODULE_NAME, ref="v0.2.0", repo="not-a-repo")
with pytest.raises(RuntimeError, match="Could not create git worktre"):
load_git(MODULE_NAME, ref="invalid-tag", repo=git_repo)
with pytest.raises(ImportError, match="ModuleNotFoundError: No module named 'not_a_real_module'"):
load_git("not_a_real_module", ref="v0.2.0", repo=git_repo)
def test_git_failures(tmp_path: Path) -> None:
"""Test failures to use Git."""
assert check(tmp_path) == 2
python-griffe-0.40.0/tests/fixtures/ 0000755 0001750 0001750 00000000000 14556223422 017254 5 ustar carsten carsten python-griffe-0.40.0/tests/fixtures/_repo/ 0000755 0001750 0001750 00000000000 14556223422 020360 5 ustar carsten carsten python-griffe-0.40.0/tests/fixtures/_repo/v0.2.0/ 0000755 0001750 0001750 00000000000 14556223422 021203 5 ustar carsten carsten python-griffe-0.40.0/tests/fixtures/_repo/v0.2.0/my_module/ 0000755 0001750 0001750 00000000000 14556223422 023175 5 ustar carsten carsten python-griffe-0.40.0/tests/fixtures/_repo/v0.2.0/my_module/__init__.py 0000644 0001750 0001750 00000000026 14556223422 025304 0 ustar carsten carsten __version__ = "0.2.0"
python-griffe-0.40.0/tests/fixtures/_repo/v0.1.0/ 0000755 0001750 0001750 00000000000 14556223422 021202 5 ustar carsten carsten python-griffe-0.40.0/tests/fixtures/_repo/v0.1.0/my_module/ 0000755 0001750 0001750 00000000000 14556223422 023174 5 ustar carsten carsten python-griffe-0.40.0/tests/fixtures/_repo/v0.1.0/my_module/__init__.py 0000644 0001750 0001750 00000000026 14556223422 025303 0 ustar carsten carsten __version__ = "0.1.0"
python-griffe-0.40.0/tests/test_inheritance.py 0000644 0001750 0001750 00000013430 14556223422 021306 0 ustar carsten carsten """Tests for class inheritance."""
from __future__ import annotations
from typing import TYPE_CHECKING, Callable
import pytest
from griffe.collections import ModulesCollection
from griffe.tests import temporary_inspected_module, temporary_visited_module
if TYPE_CHECKING:
from griffe.dataclasses import Class
def _mro_paths(cls: Class) -> list[str]:
return [base.path for base in cls.mro()]
@pytest.mark.parametrize("agent1", [temporary_visited_module, temporary_inspected_module])
@pytest.mark.parametrize("agent2", [temporary_visited_module, temporary_inspected_module])
def test_loading_inherited_members(agent1: Callable, agent2: Callable) -> None:
"""Test basic class inheritance.
Parameters:
agent1: A parametrized agent to load a module.
agent2: A parametrized agent to load a module.
"""
code1 = """
class A:
attr_from_a = 0
def method_from_a(self): ...
class B(A):
attr_from_a = 1
attr_from_b = 1
def method_from_b(self): ...
"""
code2 = """
from module1 import B
class C(B):
attr_from_c = 2
def method_from_c(self): ...
class D(C):
attr_from_a = 3
attr_from_d = 3
def method_from_d(self): ...
"""
inspection_options = {}
collection = ModulesCollection()
with agent1(code1, module_name="module1", modules_collection=collection) as module1:
if agent2 is temporary_inspected_module:
inspection_options["import_paths"] = [module1.filepath.parent]
with agent2(code2, module_name="module2", modules_collection=collection, **inspection_options) as module2:
classa = module1["A"]
classb = module1["B"]
classc = module2["C"]
classd = module2["D"]
assert classa in classb.resolved_bases
assert classb in classc.resolved_bases
assert classc in classd.resolved_bases
classd_mro = classd.mro()
assert classa in classd_mro
assert classb in classd_mro
assert classc in classd_mro
inherited_members = classd.inherited_members
assert "attr_from_a" not in inherited_members # overwritten
assert "attr_from_b" in inherited_members
assert "attr_from_c" in inherited_members
assert "attr_from_d" not in inherited_members # own-declared
assert "method_from_a" in inherited_members
assert "method_from_b" in inherited_members
assert "method_from_c" in inherited_members
assert "method_from_d" not in inherited_members # own-declared
assert "attr_from_b" in classd.all_members
@pytest.mark.parametrize("agent", [temporary_visited_module, temporary_inspected_module])
def test_nested_class_inheritance(agent: Callable) -> None:
"""Test nested class inheritance.
Parameters:
agent: A parametrized agent to load a module.
"""
code = """
class A:
class B:
attr_from_b = 0
class C(A.B):
attr_from_c = 1
"""
with agent(code) as module:
assert "attr_from_b" in module["C"].inherited_members
code = """
class OuterA:
class Inner: ...
class OuterB(OuterA):
class Inner(OuterA.Inner): ...
class OuterC(OuterA):
class Inner(OuterA.Inner): ...
class OuterD(OuterC):
class Inner(OuterC.Inner, OuterB.Inner): ...
"""
with temporary_visited_module(code) as module:
assert _mro_paths(module["OuterD.Inner"]) == [
"module.OuterC.Inner",
"module.OuterB.Inner",
"module.OuterA.Inner",
]
@pytest.mark.parametrize(
("classes", "cls", "expected_mro"),
[
(["A", "B(A)"], "B", ["A"]),
(["A", "B(A)", "C(A)", "D(B, C)"], "D", ["B", "C", "A"]),
(["A", "B(A)", "C(A)", "D(C, B)"], "D", ["C", "B", "A"]),
(["A(Z)"], "A", []),
(["A(str)"], "A", []),
(["A", "B(A)", "C(B)", "D(C)"], "D", ["C", "B", "A"]),
(["A", "B(A)", "C(B)", "D(C)", "E(A)", "F(B)", "G(F, E)", "H(G, D)"], "H", ["G", "F", "D", "C", "B", "E", "A"]),
(["A", "B(A[T])", "C(B[T])"], "C", ["B", "A"]),
],
)
def test_computing_mro(classes: list[str], cls: str, expected_mro: list[str]) -> None:
"""Test computing MRO.
Parameters:
classes: A list of classes inheriting from each other.
cls: The class to compute the MRO of.
expected_mro: The expected computed MRO.
"""
code = "class " + ": ...\nclass ".join(classes) + ": ..."
with temporary_visited_module(code) as module:
assert _mro_paths(module[cls]) == [f"module.{base}" for base in expected_mro]
@pytest.mark.parametrize(
("classes", "cls"),
[
(["A", "B(A, A)"], "B"),
(["A(D)", "B", "C(A, B)", "D(C)"], "D"),
],
)
def test_uncomputable_mro(classes: list[str], cls: str) -> None:
"""Test uncomputable MRO.
Parameters:
classes: A list of classes inheriting from each other.
cls: The class to compute the MRO of.
"""
code = "class " + ": ...\nclass ".join(classes) + ": ..."
with temporary_visited_module(code) as module, pytest.raises(ValueError, match="Cannot compute C3 linearization"):
_mro_paths(module[cls])
def test_dynamic_base_classes() -> None:
"""Test dynamic base classes."""
code = """
from collections import namedtuple
class A(namedtuple("B", "attrb")):
attra = 0
"""
with temporary_visited_module(code) as module:
assert _mro_paths(module["A"]) == [] # not supported
with temporary_inspected_module(code) as module:
assert _mro_paths(module["A"]) == [] # not supported either
python-griffe-0.40.0/tests/conftest.py 0000644 0001750 0001750 00000000057 14556223422 017604 0 ustar carsten carsten """Configuration for the pytest test suite."""
python-griffe-0.40.0/tests/test_docstrings/ 0000755 0001750 0001750 00000000000 14556223422 020621 5 ustar carsten carsten python-griffe-0.40.0/tests/test_docstrings/conftest.py 0000644 0001750 0001750 00000001460 14556223422 023021 0 ustar carsten carsten """Pytest fixture for docstrings tests."""
from __future__ import annotations
from typing import Iterator
import pytest
from griffe.docstrings import google, numpy, sphinx
from tests.test_docstrings.helpers import ParserType, parser
@pytest.fixture()
def parse_google() -> Iterator[ParserType]:
"""Yield a function to parse Google docstrings.
Yields:
A parser function.
"""
yield from parser(google)
@pytest.fixture()
def parse_numpy() -> Iterator[ParserType]:
"""Yield a function to parse Numpy docstrings.
Yields:
A parser function.
"""
yield from parser(numpy)
@pytest.fixture()
def parse_sphinx() -> Iterator[ParserType]:
"""Yield a function to parse Sphinx docstrings.
Yields:
A parser function.
"""
yield from parser(sphinx)
python-griffe-0.40.0/tests/test_docstrings/helpers.py 0000644 0001750 0001750 00000006320 14556223422 022636 0 ustar carsten carsten """This module contains helpers for testing docstring parsing."""
from __future__ import annotations
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.logger import LogLevel
if TYPE_CHECKING:
from types import ModuleType
ParentType = Union[Module, Class, Function, Attribute, None]
ParseResultType = Tuple[List[DocstringSection], List[str]]
class ParserType(Protocol): # noqa: D101
def __call__( # noqa: D102
self,
docstring: str,
parent: ParentType | None = None,
**parser_opts: Any,
) -> ParseResultType: ...
def parser(parser_module: ModuleType) -> Iterator[ParserType]:
"""Wrap a parser to help testing.
Parameters:
parser_module: The parser module containing a `parse` function.
Yields:
The wrapped function.
"""
original_warn = parser_module._warn
def parse(docstring: str, parent: ParentType | None = None, **parser_opts: Any) -> ParseResultType:
"""Parse a doctring.
Parameters:
docstring: The docstring to parse.
parent: The docstring's parent object.
**parser_opts: Additional options accepted by the parser.
Returns:
The parsed sections, and warnings.
"""
docstring_object = Docstring(docstring, lineno=1, endlineno=None)
docstring_object.endlineno = len(docstring_object.lines) + 1
if parent is not None:
docstring_object.parent = parent
parent.docstring = docstring_object
warnings = []
parser_module._warn = lambda _docstring, _offset, message, log_level=LogLevel.warning: warnings.append(message) # type: ignore[attr-defined]
sections = parser_module.parse(docstring_object, **parser_opts)
return sections, warnings
yield parse
parser_module._warn = original_warn # type: ignore[attr-defined]
def assert_parameter_equal(actual: DocstringParameter, expected: DocstringParameter) -> None:
"""Help assert docstring parameters are equal.
Parameters:
actual: The actual parameter.
expected: The expected parameter.
"""
assert actual.name == expected.name
assert_element_equal(actual, expected)
assert actual.value == expected.value
def assert_attribute_equal(actual: DocstringAttribute, expected: DocstringAttribute) -> None:
"""Help assert docstring attributes are equal.
Parameters:
actual: The actual attribute.
expected: The expected attribute.
"""
assert actual.name == expected.name
assert_element_equal(actual, expected)
def assert_element_equal(actual: DocstringElement, expected: DocstringElement) -> None:
"""Help assert docstring elements are equal.
Parameters:
actual: The actual element.
expected: The expected element.
"""
assert isinstance(actual, type(expected))
for k in actual.as_dict():
src = getattr(actual, k)
dst = getattr(expected, k)
assert src == dst, f"attribute {k!r}, {src!r} != {dst!r}"
python-griffe-0.40.0/tests/test_docstrings/test_sphinx.py 0000644 0001750 0001750 00000070074 14556223422 023553 0 ustar carsten carsten """Tests for the [Sphinx-style parser][griffe.docstrings.sphinx]."""
from __future__ import annotations
import inspect
from typing import TYPE_CHECKING
import pytest
from griffe.dataclasses import Attribute, Class, Function, Module, Parameter, Parameters
from griffe.docstrings.dataclasses import (
DocstringAttribute,
DocstringParameter,
DocstringRaise,
DocstringReturn,
DocstringSectionKind,
)
from tests.test_docstrings.helpers import assert_attribute_equal, assert_element_equal, assert_parameter_equal
if TYPE_CHECKING:
from tests.test_docstrings.helpers import ParserType
SOME_NAME = "foo"
SOME_TEXT = "descriptive test text"
SOME_EXTRA_TEXT = "more test text"
SOME_EXCEPTION_NAME = "SomeException"
SOME_OTHER_EXCEPTION_NAME = "SomeOtherException"
@pytest.mark.parametrize(
"docstring",
[
"One line docstring description",
"""
Multiple line docstring description.
With more text.
""",
],
)
def test_parse__description_only_docstring__single_markdown_section(parse_sphinx: ParserType, docstring: str) -> None:
"""Parse a single or multiline docstring.
Parameters:
parse_sphinx: Fixture parser.
docstring: A parametrized docstring.
"""
sections, warnings = parse_sphinx(docstring)
assert len(sections) == 1
assert sections[0].kind is DocstringSectionKind.text
assert sections[0].value == inspect.cleandoc(docstring)
assert not warnings
def test_parse__no_description__single_markdown_section(parse_sphinx: ParserType) -> None:
"""Parse an empty docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
sections, warnings = parse_sphinx("")
assert len(sections) == 1
assert sections[0].kind is DocstringSectionKind.text
assert sections[0].value == ""
assert not warnings
def test_parse__multiple_blank_lines_before_description__single_markdown_section(parse_sphinx: ParserType) -> None:
"""Parse a docstring with initial blank lines.
Parameters:
parse_sphinx: Fixture parser.
"""
sections, warnings = parse_sphinx(
"""
Now text""",
)
assert len(sections) == 1
assert sections[0].kind is DocstringSectionKind.text
assert sections[0].value == "Now text"
assert not warnings
def test_parse__param_field__param_section(parse_sphinx: ParserType) -> None:
"""Parse a parameter section.
Parameters:
parse_sphinx: Fixture parser.
"""
sections, _ = parse_sphinx(
f"""
Docstring with one line param.
:param {SOME_NAME}: {SOME_TEXT}
""",
)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(sections[1].value[0], DocstringParameter(SOME_NAME, description=SOME_TEXT))
def test_parse__only_param_field__empty_markdown(parse_sphinx: ParserType) -> None:
"""Parse only a parameter section.
Parameters:
parse_sphinx: Fixture parser.
"""
sections, _ = parse_sphinx(":param foo: text")
assert len(sections) == 2
assert sections[0].kind is DocstringSectionKind.text
assert sections[0].value == ""
@pytest.mark.parametrize(
"param_directive_name",
[
"param",
"parameter",
"arg",
"arguments",
"key",
"keyword",
],
)
def test_parse__all_param_names__param_section(parse_sphinx: ParserType, param_directive_name: str) -> None:
"""Parse all parameters directives.
Parameters:
parse_sphinx: Fixture parser.
param_directive_name: A parametrized directive name.
"""
sections, _ = parse_sphinx(
f"""
Docstring with one line param.
:{param_directive_name} {SOME_NAME}: {SOME_TEXT}
""",
)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(sections[1].value[0], DocstringParameter(SOME_NAME, description=SOME_TEXT))
@pytest.mark.parametrize(
"docstring",
[
f"""
Docstring with param with continuation, no indent.
:param {SOME_NAME}: {SOME_TEXT}
{SOME_EXTRA_TEXT}
""",
f"""
Docstring with param with continuation, with indent.
:param {SOME_NAME}: {SOME_TEXT}
{SOME_EXTRA_TEXT}
""",
],
)
def test_parse__param_field_multi_line__param_section(parse_sphinx: ParserType, docstring: str) -> None:
"""Parse multiline directives.
Parameters:
parse_sphinx: Fixture parser.
docstring: A parametrized docstring.
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, description=f"{SOME_TEXT} {SOME_EXTRA_TEXT}"),
)
def test_parse__param_field_for_function__param_section_with_kind(parse_sphinx: ParserType) -> None:
"""Parse parameters.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param foo: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, description=SOME_TEXT),
)
def test_parse__param_field_docs_type__param_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse parameters with types.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param str foo: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, annotation="str", description=SOME_TEXT),
)
def test_parse__param_field_type_field__param_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse parameters with separated types.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param foo: {SOME_TEXT}
:type foo: str
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, annotation="str", description=SOME_TEXT),
)
def test_parse__param_field_type_field_first__param_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse parameters with separated types first.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:type foo: str
:param foo: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, annotation="str", description=SOME_TEXT),
)
@pytest.mark.parametrize("union", ["str or None", "None or str", "str or int", "str or int or float"])
def test_parse__param_field_type_field_or_none__param_section_with_optional(
parse_sphinx: ParserType,
union: str,
) -> None:
"""Parse parameters with separated union types.
Parameters:
parse_sphinx: Fixture parser.
union: A parametrized union type.
"""
docstring = f"""
Docstring with line continuation.
:param foo: {SOME_TEXT}
:type foo: {union}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, annotation=union.replace(" or ", " | "), description=SOME_TEXT),
)
def test_parse__param_field_annotate_type__param_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param foo: {SOME_TEXT}
"""
sections, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", annotation="str", kind=None))),
)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter(SOME_NAME, annotation="str", description=SOME_TEXT),
)
assert not warnings
def test_parse__param_field_no_matching_param__result_from_docstring(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param other: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter("other", description=SOME_TEXT),
)
def test_parse__param_field_with_default__result_from_docstring(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param foo: {SOME_TEXT}
"""
sections, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", kind=None, default=repr("")))),
)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.parameters
assert_parameter_equal(
sections[1].value[0],
DocstringParameter("foo", description=SOME_TEXT, value=repr("")),
)
assert not warnings
def test_parse__param_field_no_matching_param__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param other: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "No matching parameter for 'other'" in warnings[0]
def test_parse__invalid_param_field_only_initial_marker__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param foo {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get ':directive: value' pair" in warnings[0]
def test_parse__invalid_param_field_wrong_part_count__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to parse field directive" in warnings[0]
def test_parse__param_twice__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param foo: {SOME_TEXT}
:param foo: {SOME_TEXT} again
"""
_, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", kind=None))),
)
assert "Duplicate parameter entry for 'foo'" in warnings[0]
def test_parse__param_type_twice_doc__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param str foo: {SOME_TEXT}
:type foo: str
"""
_, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", kind=None))),
)
assert "Duplicate parameter information for 'foo'" in warnings[0]
def test_parse__param_type_twice_type_directive_first__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:type foo: str
:param str foo: {SOME_TEXT}
"""
_, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", kind=None))),
)
assert "Duplicate parameter information for 'foo'" in warnings[0]
def test_parse__param_type_twice_annotated__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param str foo: {SOME_TEXT}
:type foo: str
"""
_, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", annotation="str", kind=None))),
)
assert "Duplicate parameter information for 'foo'" in warnings[0]
def test_warn_about_unknown_parameters(parse_sphinx: ParserType) -> None:
"""Warn about unknown parameters in "Parameters" sections.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = """
:param str a: {SOME_TEXT}
"""
_, warnings = parse_sphinx(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("b"),
),
),
)
assert len(warnings) == 1
assert "Parameter 'a' does not appear in the function signature" in warnings[0]
def test_parse__param_type_no_type__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param str foo: {SOME_TEXT}
:type str
"""
_, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", annotation="str", kind=None))),
)
assert "Failed to get ':directive: value' pair from" in warnings[0]
def test_parse__param_type_no_name__error_message(parse_sphinx: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Docstring with line continuation.
:param str foo: {SOME_TEXT}
:type: str
"""
_, warnings = parse_sphinx(
docstring,
parent=Function("func", parameters=Parameters(Parameter("foo", annotation="str", kind=None))),
)
assert "Failed to get parameter name from" in warnings[0]
@pytest.mark.parametrize(
"docstring",
[
f"""
Docstring with param with continuation, no indent.
:var {SOME_NAME}: {SOME_TEXT}
{SOME_EXTRA_TEXT}
""",
f"""
Docstring with param with continuation, with indent.
:var {SOME_NAME}: {SOME_TEXT}
{SOME_EXTRA_TEXT}
""",
],
)
def test_parse__attribute_field_multi_line__param_section(parse_sphinx: ParserType, docstring: str) -> None:
"""Parse multiline attributes.
Parameters:
parse_sphinx: Fixture parser.
docstring: A parametrized docstring.
"""
sections, warnings = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.attributes
assert_attribute_equal(
sections[1].value[0],
DocstringAttribute(SOME_NAME, description=f"{SOME_TEXT} {SOME_EXTRA_TEXT}"),
)
assert not warnings
@pytest.mark.parametrize(
"attribute_directive_name",
[
"var",
"ivar",
"cvar",
],
)
def test_parse__all_attribute_names__param_section(parse_sphinx: ParserType, attribute_directive_name: str) -> None:
"""Parse all attributes directives.
Parameters:
parse_sphinx: Fixture parser.
attribute_directive_name: A parametrized directive name.
"""
sections, warnings = parse_sphinx(
f"""
Docstring with one line attribute.
:{attribute_directive_name} {SOME_NAME}: {SOME_TEXT}
""",
)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.attributes
assert_attribute_equal(
sections[1].value[0],
DocstringAttribute(SOME_NAME, description=SOME_TEXT),
)
assert not warnings
def test_parse__class_attributes__attributes_section(parse_sphinx: ParserType) -> None:
"""Parse class attributes.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:var foo: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring, parent=Class("klass"))
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.attributes
assert_attribute_equal(
sections[1].value[0],
DocstringAttribute(SOME_NAME, description=SOME_TEXT),
)
def test_parse__class_attributes_with_type__annotation_in_attributes_section(parse_sphinx: ParserType) -> None:
"""Parse typed class attributes.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:vartype foo: str
:var foo: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring, parent=Class("klass"))
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.attributes
assert_attribute_equal(
sections[1].value[0],
DocstringAttribute(SOME_NAME, annotation="str", description=SOME_TEXT),
)
def test_parse__attribute_invalid_directive___error(parse_sphinx: ParserType) -> None:
"""Warn on invalid attribute directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:var {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get ':directive: value' pair from" in warnings[0]
def test_parse__attribute_no_name__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid attribute directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:var: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to parse field directive from" in warnings[0]
def test_parse__attribute_duplicate__error(parse_sphinx: ParserType) -> None:
"""Warn on duplicate attribute directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:var foo: {SOME_TEXT}
:var foo: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Duplicate attribute entry for 'foo'" in warnings[0]
def test_parse__class_attributes_type_invalid__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid attribute type directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:vartype str
:var foo: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get ':directive: value' pair from " in warnings[0]
def test_parse__class_attributes_type_no_name__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid attribute directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Class docstring with attributes
:vartype: str
:var foo: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get attribute name from" in warnings[0]
def test_parse__return_directive__return_section_no_type(parse_sphinx: ParserType) -> None:
"""Parse return directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return directive
:return: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.returns
assert_element_equal(
sections[1].value[0],
DocstringReturn(name="", annotation=None, description=SOME_TEXT),
)
def test_parse__return_directive_rtype__return_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse typed return directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return & rtype directive
:return: {SOME_TEXT}
:rtype: str
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.returns
assert_element_equal(
sections[1].value[0],
DocstringReturn(name="", annotation="str", description=SOME_TEXT),
)
def test_parse__return_directive_rtype_first__return_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse typed-first return directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return & rtype directive
:rtype: str
:return: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.returns
assert_element_equal(
sections[1].value[0],
DocstringReturn(name="", annotation="str", description=SOME_TEXT),
)
def test_parse__return_directive_annotation__return_section_with_type(parse_sphinx: ParserType) -> None:
"""Parse return directives with return annotation.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with return directive, rtype directive, & annotation
:return: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring, parent=Function("func", returns="str"))
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.returns
assert_element_equal(
sections[1].value[0],
DocstringReturn(name="", annotation="str", description=SOME_TEXT),
)
def test_parse__return_directive_annotation__prefer_return_directive(parse_sphinx: ParserType) -> None:
"""Prefer docstring type over return annotation.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with return directive, rtype directive, & annotation
:return: {SOME_TEXT}
:rtype: str
"""
sections, _ = parse_sphinx(docstring, parent=Function("func", returns="int"))
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.returns
assert_element_equal(
sections[1].value[0],
DocstringReturn(name="", annotation="str", description=SOME_TEXT),
)
def test_parse__return_invalid__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid return directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return directive
:return {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get ':directive: value' pair from " in warnings[0]
def test_parse__rtype_invalid__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid typed return directive.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = """
Function with only return directive
:rtype str
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get ':directive: value' pair from " in warnings[0]
def test_parse__raises_directive__exception_section(parse_sphinx: ParserType) -> None:
"""Parse raise directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return directive
:raise SomeException: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.raises
assert_element_equal(
sections[1].value[0],
DocstringRaise(annotation=SOME_EXCEPTION_NAME, description=SOME_TEXT),
)
def test_parse__multiple_raises_directive__exception_section_with_two(parse_sphinx: ParserType) -> None:
"""Parse multiple raise directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return directive
:raise SomeException: {SOME_TEXT}
:raise SomeOtherException: {SOME_TEXT}
"""
sections, _ = parse_sphinx(docstring)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.raises
assert_element_equal(
sections[1].value[0],
DocstringRaise(annotation=SOME_EXCEPTION_NAME, description=SOME_TEXT),
)
assert_element_equal(
sections[1].value[1],
DocstringRaise(annotation=SOME_OTHER_EXCEPTION_NAME, description=SOME_TEXT),
)
@pytest.mark.parametrize(
"raise_directive_name",
[
"raises",
"raise",
"except",
"exception",
],
)
def test_parse__all_exception_names__param_section(parse_sphinx: ParserType, raise_directive_name: str) -> None:
"""Parse all raise directives.
Parameters:
parse_sphinx: Fixture parser.
raise_directive_name: A parametrized directive name.
"""
sections, _ = parse_sphinx(
f"""
Docstring with one line attribute.
:{raise_directive_name} {SOME_EXCEPTION_NAME}: {SOME_TEXT}
""",
)
assert len(sections) == 2
assert sections[1].kind is DocstringSectionKind.raises
assert_element_equal(
sections[1].value[0],
DocstringRaise(annotation=SOME_EXCEPTION_NAME, description=SOME_TEXT),
)
def test_parse__raise_invalid__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid raise directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return directive
:raise {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to get ':directive: value' pair from " in warnings[0]
def test_parse__raise_no_name__error(parse_sphinx: ParserType) -> None:
"""Warn on invalid raise directives.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = f"""
Function with only return directive
:raise: {SOME_TEXT}
"""
_, warnings = parse_sphinx(docstring)
assert "Failed to parse exception directive from" in warnings[0]
def test_parse_module_attributes_section__expected_attributes_section(parse_sphinx: ParserType) -> None:
"""Parse attributes section in modules.
Parameters:
parse_sphinx: Fixture parser.
"""
docstring = """
Let's describe some attributes.
:var A: Alpha.
:vartype B: bytes
:var B: Beta.
:var C: Gamma.
:var D: Delta.
:var E: Epsilon.
:vartype E: float
"""
module = Module("mod", filepath=None)
module["A"] = Attribute("A", annotation="int", value="0")
module["B"] = Attribute("B", annotation="str", value=repr("ŧ"))
module["C"] = Attribute("C", annotation="bool", value="True")
module["D"] = Attribute("D", annotation=None, value="3.0")
module["E"] = Attribute("E", annotation=None, value="None")
sections, warnings = parse_sphinx(docstring, parent=module)
attr_section = sections[1]
assert attr_section.kind is DocstringSectionKind.attributes
assert len(attr_section.value) == 5
expected_kwargs = [
{"name": "A", "annotation": "int", "description": "Alpha."},
{"name": "B", "annotation": "bytes", "description": "Beta."},
{"name": "C", "annotation": "bool", "description": "Gamma."},
{"name": "D", "annotation": None, "description": "Delta."},
{"name": "E", "annotation": "float", "description": "Epsilon."},
]
for index, expected in enumerate(expected_kwargs):
assert_attribute_equal(attr_section.value[index], DocstringAttribute(**expected)) # type: ignore[arg-type]
assert not warnings
python-griffe-0.40.0/tests/test_docstrings/test_warnings.py 0000644 0001750 0001750 00000001565 14556223422 024071 0 ustar carsten carsten """Tests for the docstrings utility functions."""
from __future__ import annotations
from griffe.dataclasses import Docstring, Function, Parameter, ParameterKind, Parameters
from griffe.docstrings.parsers import Parser, parse
def test_can_warn_without_parent_module() -> None:
"""Assert we can parse a docstring even if it does not have a parent module."""
function = Function(
"func",
parameters=Parameters(
Parameter("param1", annotation=None, kind=ParameterKind.positional_or_keyword), # I only changed this line
Parameter("param2", annotation="int", kind=ParameterKind.keyword_only),
),
)
text = """
Hello I'm a docstring!
Parameters:
param1: Description.
param2: Description.
"""
docstring = Docstring(text, lineno=1, parent=function)
assert parse(docstring, Parser.google)
python-griffe-0.40.0/tests/test_docstrings/__init__.py 0000644 0001750 0001750 00000000034 14556223422 022727 0 ustar carsten carsten """Tests for docstrings."""
python-griffe-0.40.0/tests/test_docstrings/test_google.py 0000644 0001750 0001750 00000124042 14556223422 023511 0 ustar carsten carsten """Tests for the [Google-style parser][griffe.docstrings.google]."""
from __future__ import annotations
import inspect
from typing import TYPE_CHECKING
import pytest
from griffe.dataclasses import Attribute, Class, Docstring, Function, Module, Parameter, Parameters
from griffe.docstrings.dataclasses import DocstringReturn, DocstringSectionKind
from griffe.docstrings.utils import parse_annotation
from griffe.expressions import ExprName
if TYPE_CHECKING:
from tests.test_docstrings.helpers import ParserType
# =============================================================================================
# Markup flow (multilines, indentation, etc.)
def test_simple_docstring(parse_google: ParserType) -> None:
"""Parse a simple docstring.
Parameters:
parse_google: Fixture parser.
"""
sections, warnings = parse_google("A simple docstring.")
assert len(sections) == 1
assert not warnings
def test_multiline_docstring(parse_google: ParserType) -> None:
"""Parse a multi-line docstring.
Parameters:
parse_google: Fixture parser.
"""
sections, warnings = parse_google(
"""
A somewhat longer docstring.
Blablablabla.
""",
)
assert len(sections) == 1
assert not warnings
def test_parse_partially_indented_lines(parse_google: ParserType) -> None:
"""Properly handle partially indented lines.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
The available formats are:
- JSON
The unavailable formats are:
- YAML
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 2
assert sections[0].kind is DocstringSectionKind.admonition
assert sections[1].kind is DocstringSectionKind.admonition
assert not warnings
def test_multiple_lines_in_sections_items(parse_google: ParserType) -> None:
"""Parse multi-line item description.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
p (int): This parameter
has a description
spawning on multiple lines.
It even has blank lines in it.
Some of these lines
are indented for no reason.
q (int):
What if the first line is blank?
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert len(sections[0].value) == 2
assert warnings
for warning in warnings:
assert "should be 4 * 2 = 8 spaces, not" in warning
def test_code_blocks(parse_google: ParserType) -> None:
"""Parse code blocks.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
This docstring contains a code block!
```python
print("hello")
```
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert not warnings
def test_indented_code_block(parse_google: ParserType) -> None:
"""Parse indented code blocks.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
This docstring contains a docstring in a code block o_O!
\"\"\"
This docstring is contained in another docstring O_o!
Parameters:
s: A string.
\"\"\"
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert not warnings
def test_different_indentation(parse_google: ParserType) -> None:
"""Parse different indentations, warn on confusing indentation.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Raises:
StartAt5: this section's items starts with 5 spaces of indentation.
Well indented continuation line.
Badly indented continuation line (will trigger a warning).
Empty lines are preserved, as well as extra-indentation (this line is a code block).
AnyOtherLine: ...starting with exactly 5 spaces is a new item.
AnyLine: ...indented with less than 5 spaces signifies the end of the section.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 2
assert len(sections[0].value) == 2
assert sections[0].value[0].description == (
"this section's items starts with 5 spaces of indentation.\n"
"Well indented continuation line.\n"
"Badly indented continuation line (will trigger a warning).\n"
"\n"
" Empty lines are preserved, as well as extra-indentation (this line is a code block)."
)
assert sections[1].value == " AnyLine: ...indented with less than 5 spaces signifies the end of the section."
assert len(warnings) == 1
assert "should be 5 * 2 = 10 spaces, not 6" in warnings[0]
def test_empty_indented_lines_in_section_with_items(parse_google: ParserType) -> None:
"""In sections with items, don't treat lines with just indentation as items.
Parameters:
parse_google: Fixture parser.
"""
docstring = "Returns:\n only_item: Description.\n \n \n\nSomething."
sections, _ = parse_google(docstring)
assert len(sections) == 2
assert len(sections[0].value) == 1
@pytest.mark.parametrize(
"section",
[
"Attributes",
"Other Parameters",
"Parameters",
"Raises",
"Receives",
"Returns",
"Warns",
"Yields",
],
)
def test_starting_item_description_on_new_line(parse_google: ParserType, section: str) -> None:
"""In sections with items, allow starting item descriptions on a new (indented) line.
Parameters:
parse_google: Fixture parser.
section: A parametrized section name.
"""
docstring = f"\n{section}:\n only_item:\n Description."
sections, _ = parse_google(docstring)
assert len(sections) == 1
assert len(sections[0].value) == 1
assert sections[0].value[0].description.strip() == "Description."
# =============================================================================================
# Annotations
def test_parse_without_parent(parse_google: ParserType) -> None:
"""Parse a docstring without a parent function.
Parameters:
parse_google: Fixture parser.
"""
sections, warnings = parse_google(
"""
Parameters:
void: SEGFAULT.
niet: SEGFAULT.
nada: SEGFAULT.
rien: SEGFAULT.
Keyword Args:
keywd: SEGFAULT.
Exceptions:
GlobalError: when nothing works as expected.
Returns:
Itself.
""",
)
assert len(sections) == 4
assert len(warnings) == 6 # missing annotations for parameters and return
for warning in warnings[:-1]:
assert "parameter" in warning
assert "return" in warnings[-1]
def test_parse_without_annotations(parse_google: ParserType) -> None:
"""Parse a function docstring without signature annotations.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x: X value.
Keyword Args:
y: Y value.
Returns:
Sum X + Y + Z.
"""
sections, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("x"),
Parameter("y"),
),
),
)
assert len(sections) == 3
assert len(warnings) == 3
for warning in warnings[:-1]:
assert "parameter" in warning
assert "return" in warnings[-1]
def test_parse_with_annotations(parse_google: ParserType) -> None:
"""Parse a function docstring with signature annotations.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x: X value.
Keyword Parameters:
y: Y value.
Returns:
Sum X + Y.
"""
sections, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("x", annotation="int"),
Parameter("y", annotation="int"),
),
returns="int",
),
)
assert len(sections) == 3
assert not warnings
# =============================================================================================
# Sections
def test_parse_attributes_section(parse_google: ParserType) -> None:
"""Parse Attributes sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Attributes:
hey: Hey.
ho: Ho.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert not warnings
def test_parse_functions_section(parse_google: ParserType) -> None:
"""Parse Functions/Methods sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Functions:
f(a, b=2): Hello.
g: Hi.
Methods:
f(a, b=2): Hello.
g: Hi.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 2
for section in sections:
assert section.kind is DocstringSectionKind.functions
func_f = section.value[0]
assert func_f.name == "f"
assert func_f.signature == "f(a, b=2)"
assert func_f.description == "Hello."
func_g = section.value[1]
assert func_g.name == "g"
assert func_g.signature is None
assert func_g.description == "Hi."
assert not warnings
def test_parse_classes_section(parse_google: ParserType) -> None:
"""Parse Classes sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Classes:
C(a, b=2): Hello.
D: Hi.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert sections[0].kind is DocstringSectionKind.classes
class_c = sections[0].value[0]
assert class_c.name == "C"
assert class_c.signature == "C(a, b=2)"
assert class_c.description == "Hello."
class_d = sections[0].value[1]
assert class_d.name == "D"
assert class_d.signature is None
assert class_d.description == "Hi."
assert not warnings
def test_parse_modules_section(parse_google: ParserType) -> None:
"""Parse Modules sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Modules:
m: Hello.
n: Hi.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert sections[0].kind is DocstringSectionKind.modules
module_m = sections[0].value[0]
assert module_m.name == "m"
assert module_m.description == "Hello."
module_n = sections[0].value[1]
assert module_n.name == "n"
assert module_n.description == "Hi."
assert not warnings
def test_parse_examples_sections(parse_google: ParserType) -> None:
"""Parse a function docstring with examples.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Examples:
Some examples that will create a unified code block:
>>> 2 + 2 == 5
False
>>> print("examples")
"examples"
This is just a random comment in the examples section.
These examples will generate two different code blocks. Note the blank line.
>>> print("I'm in the first code block!")
"I'm in the first code block!"
>>> print("I'm in other code block!")
"I'm in other code block!"
We also can write multiline examples:
>>> x = 3 + 2 # doctest: +SKIP
>>> y = x + 10
>>> y
15
This is just a typical Python code block:
```python
print("examples")
return 2 + 2
```
Even if it contains doctests, the following block is still considered a normal code-block.
```pycon
>>> print("examples")
"examples"
>>> 2 + 2
4
```
The blank line before an example is optional.
>>> x = 3
>>> y = "apple"
>>> z = False
>>> l = [x, y, z]
>>> my_print_list_function(l)
3
"apple"
False
"""
sections, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("x", annotation="int"),
Parameter("y", annotation="int"),
),
returns="int",
),
trim_doctest_flags=False,
)
assert len(sections) == 1
examples = sections[0]
assert len(examples.value) == 9
assert examples.value[6][1].startswith(">>> x = 3 + 2 # doctest: +SKIP")
assert not warnings
def test_parse_yields_section(parse_google: ParserType) -> None:
"""Parse Yields section.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Yields:
x: Floats.
(int): Integers.
y (int): Same.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
annotated = sections[0].value[0]
assert annotated.name == "x"
assert annotated.annotation is None
assert annotated.description == "Floats."
annotated = sections[0].value[1]
assert annotated.name == ""
assert annotated.annotation == "int"
assert annotated.description == "Integers."
annotated = sections[0].value[2]
assert annotated.name == "y"
assert annotated.annotation == "int"
assert annotated.description == "Same."
assert len(warnings) == 1
assert "'x'" in warnings[0]
def test_invalid_sections(parse_google: ParserType) -> None:
"""Warn on invalid sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
Exceptions:
Exceptions:
Returns:
Note:
Important:
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert not warnings
# =============================================================================================
# Parameters sections
def test_parse_args_and_kwargs(parse_google: ParserType) -> None:
"""Parse args and kwargs.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
a (str): a parameter.
*args (str): args parameters.
**kwargs (str): kwargs parameters.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
expected_parameters = {"a": "a parameter.", "*args": "args parameters.", "**kwargs": "kwargs parameters."}
for parameter in sections[0].value:
assert parameter.name in expected_parameters
assert expected_parameters[parameter.name] == parameter.description
assert not warnings
def test_parse_args_kwargs_keyword_only(parse_google: ParserType) -> None:
"""Parse args and kwargs.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
a (str): a parameter.
*args (str): args parameters.
Keyword Args:
**kwargs (str): kwargs parameters.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 2
expected_parameters = {"a": "a parameter.", "*args": "args parameters."}
for parameter in sections[0].value:
assert parameter.name in expected_parameters
assert expected_parameters[parameter.name] == parameter.description
expected_parameters = {"**kwargs": "kwargs parameters."}
for kwarg in sections[1].value:
assert kwarg.name in expected_parameters
assert expected_parameters[kwarg.name] == kwarg.description
assert not warnings
def test_parse_types_in_docstring(parse_google: ParserType) -> None:
"""Parse types in docstring.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x (int): X value.
Keyword Args:
y (int): Y value.
Returns:
s (int): Sum X + Y + Z.
"""
sections, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("x"),
Parameter("y"),
),
),
)
assert len(sections) == 3
assert not warnings
assert sections[0].kind is DocstringSectionKind.parameters
assert sections[1].kind is DocstringSectionKind.other_parameters
assert sections[2].kind is DocstringSectionKind.returns
(argx,) = sections[0].value
(argy,) = sections[1].value
(returns,) = sections[2].value
assert argx.name == "x"
assert argx.annotation.name == "int"
assert argx.annotation.canonical_path == "int"
assert argx.description == "X value."
assert argx.value is None
assert argy.name == "y"
assert argy.annotation.name == "int"
assert argy.annotation.canonical_path == "int"
assert argy.description == "Y value."
assert argy.value is None
assert returns.annotation.name == "int"
assert returns.annotation.canonical_path == "int"
assert returns.description == "Sum X + Y + Z."
def test_parse_optional_type_in_docstring(parse_google: ParserType) -> None:
"""Parse optional types in docstring.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x (int): X value.
y (int, optional): Y value.
Keyword Args:
z (int, optional): Z value.
"""
sections, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("x", default="1"),
Parameter("y", default="None"),
Parameter("z", default="None"),
),
),
)
assert len(sections) == 2
assert not warnings
assert sections[0].kind is DocstringSectionKind.parameters
assert sections[1].kind is DocstringSectionKind.other_parameters
argx, argy = sections[0].value
(argz,) = sections[1].value
assert argx.name == "x"
assert argx.annotation.name == "int"
assert argx.annotation.canonical_path == "int"
assert argx.description == "X value."
assert argx.value == "1"
assert argy.name == "y"
assert argy.annotation.name == "int"
assert argy.annotation.canonical_path == "int"
assert argy.description == "Y value."
assert argy.value == "None"
assert argz.name == "z"
assert argz.annotation.name == "int"
assert argz.annotation.canonical_path == "int"
assert argz.description == "Z value."
assert argz.value == "None"
def test_prefer_docstring_types_over_annotations(parse_google: ParserType) -> None:
"""Prefer the docstring type over the annotation.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x (str): X value.
Keyword Args:
y (str): Y value.
Returns:
(str): Sum X + Y + Z.
"""
sections, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("x", annotation="int"),
Parameter("y", annotation="int"),
),
returns="int",
),
)
assert len(sections) == 3
assert not warnings
assert sections[0].kind is DocstringSectionKind.parameters
assert sections[1].kind is DocstringSectionKind.other_parameters
assert sections[2].kind is DocstringSectionKind.returns
(argx,) = sections[0].value
(argy,) = sections[1].value
(returns,) = sections[2].value
assert argx.name == "x"
assert argx.annotation.name == "str"
assert argx.annotation.canonical_path == "str"
assert argx.description == "X value."
assert argy.name == "y"
assert argy.annotation.name == "str"
assert argy.annotation.canonical_path == "str"
assert argy.description == "Y value."
assert returns.annotation.name == "str"
assert returns.annotation.canonical_path == "str"
assert returns.description == "Sum X + Y + Z."
def test_parameter_line_without_colon(parse_google: ParserType) -> None:
"""Warn when missing colon.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x is an integer.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 0 # empty sections are discarded
assert len(warnings) == 1
assert "pair" in warnings[0]
def test_parameter_line_without_colon_keyword_only(parse_google: ParserType) -> None:
"""Warn when missing colon.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Keyword Args:
x is an integer.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 0 # empty sections are discarded
assert len(warnings) == 1
assert "pair" in warnings[0]
def test_warn_about_unknown_parameters(parse_google: ParserType) -> None:
"""Warn about unknown parameters in "Parameters" sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x (int): Integer.
y (int): Integer.
"""
_, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("a"),
Parameter("y"),
),
),
)
assert len(warnings) == 1
assert "'x' does not appear in the function signature" in warnings[0]
def test_never_warn_about_unknown_other_parameters(parse_google: ParserType) -> None:
"""Never warn about unknown parameters in "Other parameters" sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Other Parameters:
x (int): Integer.
z (int): Integer.
"""
_, warnings = parse_google(
docstring,
parent=Function(
"func",
parameters=Parameters(
Parameter("a"),
Parameter("y"),
),
),
)
assert not warnings
def test_unknown_params_scan_doesnt_crash_without_parameters(parse_google: ParserType) -> None:
"""Assert we don't crash when parsing parameters sections and parent object does not have parameters.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
this (str): This.
that (str): That.
"""
_, warnings = parse_google(docstring, parent=Module("mod"))
assert not warnings
def test_class_uses_init_parameters(parse_google: ParserType) -> None:
"""Assert we use the `__init__` parameters when parsing classes' parameters sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
x: X value.
"""
parent = Class("c")
parent["__init__"] = Function("__init__", parameters=Parameters(Parameter("x", annotation="int")))
sections, warnings = parse_google(docstring, parent=parent)
assert not warnings
argx = sections[0].value[0]
assert argx.name == "x"
assert argx.annotation == "int"
assert argx.description == "X value."
def test_dataclass_uses_attributes(parse_google: ParserType) -> None:
"""Assert we use the class' attributes as parameters when parsing dataclasses' parameters sections.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Parameters:
auth: Auth method.
base_url: Base URL.
"""
parent = Class("c")
parent.labels.add("dataclass")
parent["auth"] = Attribute("auth", annotation="Optional[str]", value="None")
parent["base_url"] = Attribute("base_url", annotation="str", value="'https://api.example.com'")
sections, warnings = parse_google(docstring, parent=parent)
assert not warnings
auth, base_url = sections[0].value
assert auth.name == "auth"
assert auth.annotation == "Optional[str]"
assert auth.description == "Auth method."
assert auth.default == "None"
assert base_url.name == "base_url"
assert base_url.annotation == "str"
assert base_url.description == "Base URL."
assert base_url.default == "'https://api.example.com'"
# TODO: possible feature
# def test_missing_parameter(parse_google: ParserType) -> None:
# """Warn on missing parameter in docstring.
#
# Parameters:
# parse_google: Fixture parser.
# """
# docstring = """
# Parameters:
# x: Integer.
# """
# assert not warnings
# =============================================================================================
# Attributes sections
def test_retrieve_attributes_annotation_from_parent(parse_google: ParserType) -> None:
"""Retrieve the annotations of attributes from the parent object.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Summary.
Attributes:
a: Whatever.
b: Whatever.
"""
parent = Class("cls")
parent["a"] = Attribute("a", annotation=ExprName("int"))
parent["b"] = Attribute("b", annotation=ExprName("str"))
sections, _ = parse_google(docstring, parent=parent)
attributes = sections[1].value
assert attributes[0].name == "a"
assert attributes[0].annotation.name == "int"
assert attributes[1].name == "b"
assert attributes[1].annotation.name == "str"
# =============================================================================================
# Yields sections
def test_parse_yields_section_with_return_annotation(parse_google: ParserType) -> None:
"""Parse Yields section with a return annotation in the parent function.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Yields:
Integers.
"""
function = Function("func", returns="Iterator[int]")
sections, warnings = parse_google(docstring, function)
assert len(sections) == 1
annotated = sections[0].value[0]
assert annotated.annotation == "Iterator[int]"
assert annotated.description == "Integers."
assert not warnings
@pytest.mark.parametrize(
"return_annotation",
[
"Iterator[tuple[int, float]]",
"Generator[tuple[int, float], ..., ...]",
],
)
def test_parse_yields_tuple_in_iterator_or_generator(parse_google: ParserType, return_annotation: str) -> None:
"""Parse Yields annotations in Iterator or Generator types.
Parameters:
parse_google: Fixture parser.
return_annotation: Parametrized return annotation as a string.
"""
docstring = """
Summary.
Yields:
a: Whatever.
b: Whatever.
"""
sections, _ = parse_google(
docstring,
parent=Function(
"func",
returns=parse_annotation(return_annotation, Docstring("d", parent=Function("f"))),
),
)
yields = sections[1].value
assert yields[0].name == "a"
assert yields[0].annotation.name == "int"
assert yields[1].name == "b"
assert yields[1].annotation.name == "float"
@pytest.mark.parametrize(
"return_annotation",
[
"Iterator[int]",
"Generator[int, None, None]",
],
)
def test_extract_yielded_type_with_single_return_item(parse_google: ParserType, return_annotation: str) -> None:
"""Extract main type annotation from Iterator or Generator.
Parameters:
parse_google: Fixture parser.
return_annotation: Parametrized return annotation as a string.
"""
docstring = """
Summary.
Yields:
A number.
"""
sections, _ = parse_google(
docstring,
parent=Function(
"func",
returns=parse_annotation(return_annotation, Docstring("d", parent=Function("f"))),
),
)
yields = sections[1].value
assert yields[0].annotation.name == "int"
# =============================================================================================
# Receives sections
def test_parse_receives_tuple_in_generator(parse_google: ParserType) -> None:
"""Parse Receives annotations in Generator type.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Summary.
Receives:
a: Whatever.
b: Whatever.
"""
sections, _ = parse_google(
docstring,
parent=Function(
"func",
returns=parse_annotation("Generator[..., tuple[int, float], ...]", Docstring("d", parent=Function("f"))),
),
)
receives = sections[1].value
assert receives[0].name == "a"
assert receives[0].annotation.name == "int"
assert receives[1].name == "b"
assert receives[1].annotation.name == "float"
@pytest.mark.parametrize(
"return_annotation",
[
"Generator[int, float, None]",
],
)
def test_extract_received_type_with_single_return_item(parse_google: ParserType, return_annotation: str) -> None:
"""Extract main type annotation from Iterator or Generator.
Parameters:
parse_google: Fixture parser.
return_annotation: Parametrized return annotation as a string.
"""
docstring = """
Summary.
Receives:
A floating point number.
"""
sections, _ = parse_google(
docstring,
parent=Function(
"func",
returns=parse_annotation(return_annotation, Docstring("d", parent=Function("f"))),
),
)
receives = sections[1].value
assert receives[0].annotation.name == "float"
# =============================================================================================
# Returns sections
def test_parse_returns_tuple_in_generator(parse_google: ParserType) -> None:
"""Parse Returns annotations in Generator type.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Summary.
Returns:
a: Whatever.
b: Whatever.
"""
sections, _ = parse_google(
docstring,
parent=Function(
"func",
returns=parse_annotation("Generator[..., ..., tuple[int, float]]", Docstring("d", parent=Function("f"))),
),
)
returns = sections[1].value
assert returns[0].name == "a"
assert returns[0].annotation.name == "int"
assert returns[1].name == "b"
assert returns[1].annotation.name == "float"
# =============================================================================================
# Parser special features
def test_parse_admonitions(parse_google: ParserType) -> None:
"""Parse admonitions.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Important note:
Hello.
Note: With title.
Hello again.
Something:
Something.
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 3
assert not warnings
assert sections[0].title == "Important note"
assert sections[0].value.kind == "important-note"
assert sections[0].value.contents == "Hello."
assert sections[1].title == "With title."
assert sections[1].value.kind == "note"
assert sections[1].value.contents == "Hello again."
assert sections[2].title == "Something"
assert sections[2].value.kind == "something"
assert sections[2].value.contents == "Something."
@pytest.mark.parametrize(
"docstring",
[
"""
******************************
This looks like an admonition:
******************************
""",
"""
Warning: this line also looks
like an admonition.
""",
"""
Matching but not an admonition:
- Multiple empty lines above.
""",
"""Last line:""",
],
)
def test_handle_false_admonitions_correctly(parse_google: ParserType, docstring: str) -> None:
"""Correctly handle lines that look like admonitions.
Parameters:
parse_google: Fixture parser.
docstring: The docstring to parse (parametrized).
"""
sections, warnings = parse_google(docstring)
assert len(sections) == 1
assert sections[0].kind is DocstringSectionKind.text
assert len(sections[0].value.splitlines()) == len(inspect.cleandoc(docstring).splitlines())
assert not warnings
def test_dont_insert_admonition_before_current_section(parse_google: ParserType) -> None:
"""Check that admonitions are inserted at the right place.
Parameters:
parse_google: Fixture parser.
"""
docstring = """
Summary.
Short description.
Info:
Something useful.
"""
sections, _ = parse_google(docstring)
assert len(sections) == 2
assert sections[0].kind is DocstringSectionKind.text
assert sections[1].kind is DocstringSectionKind.admonition
@pytest.mark.parametrize(
"docstring",
[
"",
"\n",
"\n\n",
"Summary.",
"Summary.\n\n\n",
"Summary.\n\nParagraph.",
"Summary\non two lines.",
"Summary\non two lines.\n\nParagraph.",
],
)
def test_ignore_init_summary(parse_google: ParserType, docstring: str) -> None:
"""Correctly ignore summary in `__init__` methods' docstrings.
Parameters:
parse_google: Fixture parser.
docstring: The docstring to parse_google (parametrized).
"""
sections, _ = parse_google(docstring, parent=Function("__init__", parent=Class("C")), ignore_init_summary=True)
for section in sections:
assert "Summary" not in section.value
if docstring.strip():
sections, _ = parse_google(docstring, parent=Function("__init__", parent=Module("M")), ignore_init_summary=True)
assert "Summary" in sections[0].value
sections, _ = parse_google(docstring, parent=Function("f", parent=Class("C")), ignore_init_summary=True)
assert "Summary" in sections[0].value
sections, _ = parse_google(docstring, ignore_init_summary=True)
assert "Summary" in sections[0].value
@pytest.mark.parametrize(
"docstring",
[
"""
Examples:
Base case 1. We want to skip the following test.
>>> 1 + 1 == 3 # doctest: +SKIP
True
""",
r"""
Examples:
Base case 2. We have a blankline test.
>>> print("a\n\nb")
a