Annotating Third-Party APIs¶
Python ecosystem offers a lot of interesting and useful packages that are not part of the core distribution. These third-party packages often come with their own new APIs, and LineaPy is not guaranteed to handle all of them properly when removing extraneous code. For such "unrecognized" APIs, we can add instructions for LineaPy, which we call "package annotation".
For instance, without relevant package annotation, running
import pyperclip pyperclip.copy("This wont show up without annotations") tmp_var = pyperclip.paste() artifact = lineapy.save(tmp_var, "annotated_text") print(artifact.get_code())
import pyperclip tmp_var = pyperclip.paste()
pyperclip.copy step is missing. This is because
lineapy does not recognize it
as an API that modifies the caller (
pyperclip, in this case) and hence skips it
during the relevant code cleanup.
We can annotate the
pyperclip package by creating a YAML file looking as follows:
# ./pyperclip.annotations.yaml - module: pyperclip annotations: - criteria: function_names: - copy - paste side_effects: - mutated_value: self_ref: SELF_REF
modulerefers to the third-party package/module that the annotation is associated with.
criteriaspecifies what each annotation is for. In this example, it instructs that the annotation is for
pastefunctions in the module.
side_effectsspecifies what each annotation is about. In this example, it instructs that the annotation is about mutation of the function caller.
In sum, these instructions tell
lineapy to recognize
paste functions in the
as APIs that mutate their caller, and to treat them as such in relevant downstream tasks such as code cleanup.
For more details on annotation keywords, check this page.
To make the annotation take effect, we run:
lineapy annotate add "./pyperclip.annotations.yaml" --name="pyperclip_annotations"
"pyperclip_annotations" is a name of our choice.
Now, if we reload
lineapy and run the original code above, we get the correct code cleanup displayed:
import pyperclip pyperclip.copy("This wont show up without annotations") tmp_var = pyperclip.paste()
Annotations added this way are valid in the local environment only.
To integrate new annotations into the
lineapy source code, the YAML file
should be created or updated in
following contribution instructions here.
To view imported annotations, run:
lineapy annotate list
To delete imported annotations, run:
lineapy annotate delete --name=[NAME-OF-ANNOTATION]
"pyperclip_annotations" in this example.