|
| 1 | +# Set Git information and source link on objects |
| 2 | + |
| 3 | +Griffe tries to set [source information][source-information] on each package it loads. Sometimes it won't be able to find such information, or to find the correct information. In this case, you can programmatically set the right information with a Griffe extension. This will let you fix or customize the source links for many objects at once or for specific objects. |
| 4 | + |
| 5 | +## Git information on whole packages |
| 6 | + |
| 7 | +In this example we see how to set the Git information for whole packages. This will affect every object in these packages, and therefore the source link for each object. |
| 8 | + |
| 9 | +Start by creating an extensions module (a simple Python file) somewhere in your repository, if you don't already have one. Within it, create an extension class: |
| 10 | + |
| 11 | +```python |
| 12 | +import griffe |
| 13 | + |
| 14 | + |
| 15 | +class GitInfo(griffe.Extension): |
| 16 | + """An extension to set the right Git information.""" |
| 17 | +``` |
| 18 | + |
| 19 | +Next we hook onto the `on_package` event to override the `git_info` attribute of the packages we are interested into. |
| 20 | + |
| 21 | +```python |
| 22 | +from pathlib import Path |
| 23 | +from typing import Any |
| 24 | + |
| 25 | +import griffe |
| 26 | + |
| 27 | + |
| 28 | +class GitInfo(griffe.Extension): |
| 29 | + """An extension to set the right Git information.""" |
| 30 | + |
| 31 | + def on_package(self, *, pkg: griffe.Module, **kwargs: Any) -> None: |
| 32 | + if pkg.name == "my_package_name": |
| 33 | + pkg.git_info = griffe.GitInfo( |
| 34 | + repository=Path("/path/to/this/package/local/repository"), |
| 35 | + service="forgejo", |
| 36 | + remote_url="https://myhostedforge.mydomain.com/myaccount/myproject", |
| 37 | + commit_hash="77f928aeab857cb45564462a4f849c2df2cca99a", |
| 38 | + ) |
| 39 | +``` |
| 40 | + |
| 41 | +Here we hardcode the commit hash, but ideally we would obtain it by running a Git command in a subprocess, or any other way that gives a relevant commit hash. |
| 42 | + |
| 43 | +```python |
| 44 | +import subprocess |
| 45 | + |
| 46 | +process = subprocess.run(["git", "-C", repo, "rev-parse", "HEAD"], text=True, capture_output=True) |
| 47 | +commit_hash = process.stdout.strip() |
| 48 | +``` |
| 49 | + |
| 50 | +We could also reuse properties that Griffe found: |
| 51 | + |
| 52 | +```python |
| 53 | +# Here we reuse `repository` and `commit_hash` while overriding only `service` and `remote_url`. |
| 54 | +pkg.git_info = griffe.GitInfo( |
| 55 | + repository=pkg.git_info.repository, |
| 56 | + service="forgejo", |
| 57 | + remote_url="https://myhostedforge.mydomain.com/myaccount/myproject", |
| 58 | + commit_hash=pkg.git_info.commit_hash, |
| 59 | +) |
| 60 | + |
| 61 | +# We could also mutate the original `GitInfo` object: |
| 62 | +pkg.git_info.service = "forgejo" |
| 63 | +``` |
| 64 | + |
| 65 | +Now, with this extension enabled (see [Using extensions][using-extensions]), every object source link in our `my_package_name` package will be based on this Git information. For example, the source link for `my_package_name.my_function` would be something like `https://myhostedforge.mydomain.com/myaccount/myproject/src/commit/77f928aeab857cb45564462a4f849c2df2cca99a/src/my_package_name/__init__.py#L35-L48`. |
| 66 | + |
| 67 | +## Source links on specific objects |
| 68 | + |
| 69 | +Let say you expose Python objects in your API that are compiled from other sources (C extension, Pyo3 code, etc.). Let say you also know the filepath and line numbers for each of these compiled objects. With this information, you could fix the source link for these compiled objects so that they point to the actual sources, and not to the final modules, where the line numbers would be incorrect (or to nowhere since we wouldn't have line numbers in the first place). |
| 70 | + |
| 71 | +Start by creating an extensions module (a simple Python file) somewhere in your repository, if you don't already have one. Within it, create an extension class: |
| 72 | + |
| 73 | +```python |
| 74 | +import griffe |
| 75 | + |
| 76 | + |
| 77 | +class SourceLinks(griffe.Extension): |
| 78 | + """An extension to set the right source links.""" |
| 79 | +``` |
| 80 | + |
| 81 | +Next we hook onto the `on_object` event to override the `source_link` attribute of the objects we are interested into. |
| 82 | + |
| 83 | +```python |
| 84 | +from pathlib import Path |
| 85 | +from typing import Any |
| 86 | + |
| 87 | +import griffe |
| 88 | + |
| 89 | + |
| 90 | +class SourceLinks(griffe.Extension): |
| 91 | + """An extension to set the right source links.""" |
| 92 | + |
| 93 | + def on_object(self, *, obj: griffe.Object, **kwargs: Any) -> None: |
| 94 | + if obj.path == "my_package_name.my_function": |
| 95 | + obj.source_link = "https://myhostedforge.mydomain.com/myaccount/myproject/src/commit/77f928aeab857cb45564462a4f849c2df2cca99a/src/lib.rs#L35-L48" |
| 96 | + # Handle any other object you want. |
| 97 | + elif ...: |
| 98 | + ... |
| 99 | +``` |
| 100 | + |
| 101 | +Here we hardcode the link, but we can also reuse the Git information of the package to just correct the filepath and line numbers: |
| 102 | + |
| 103 | +```python |
| 104 | +from pathlib import Path |
| 105 | +from typing import Any |
| 106 | + |
| 107 | +import griffe |
| 108 | + |
| 109 | + |
| 110 | +class SourceLinks(griffe.Extension): |
| 111 | + """An extension to set the right source links.""" |
| 112 | + |
| 113 | + def on_object(self, *, obj: griffe.Object, **kwargs: Any) -> None: |
| 114 | + if obj.path == "my_package_name.my_function": |
| 115 | + obj.source_link = obj.git_info.get_source_link( |
| 116 | + filepath="src/lib.rs", |
| 117 | + lineno=35, |
| 118 | + endlineno=48, |
| 119 | + ) |
| 120 | + # Handle any other object you want. |
| 121 | + elif ...: |
| 122 | + ... |
| 123 | +``` |
0 commit comments