One of the most distinct features of a charm is the way it can readily relate to another charm. For this interface, there is one charm that will provide information in a specific way, and a charm that will consume information in a matching way to connect and work together. To ensure that the charm interface is a perfect pairing, the operator framework tooling and the store support a mechanism to publish and reuse this logic in a form of simple files, that we’ll call libraries. This tutorial will show you how to structure and publish your library so it can be easily shared and consumed.
What you’ll learn
- The standard that Charmhub uses to document and display libraries
- How to publish and access your library on charmhub.io
What you’ll need
Libraries have 2 sections of documentation:
The header of the file: this is a python comment using the triple quote:
"""Like this """. This section describes the library and supports Markdown following the CommonMark specification.
- The Python docstring: these docstrings are used to describe the functions and classes that the library provides. The docstring supports the Google Python Docstring format.
Inside a charm there is a specific directory_, _under which there are subdirectories with this naming convention:
$CHARMDIR is the project’s root (contains
hooks/, etc), and the
<charm> placeholder represents the charm responsible for the library named as
<libname>.py with API version
<libname>.py the following fields must necessarily be defined:
Default generated by the command: charmcraft create-lib
# Do not change LIBID = "abcdef12345" # Unique ID that refers to the library forever LIBAPI = 3 # API version for non-backwards compatibility evolution LIBPATCH = 2 # A patch version for all non-breaking changes def function(): return "foo" class Example: def __init__(self, foo, bar): self.foo = foo self.bar = bar def info(self, add): return add + self.foo
Describe this class by adding a section at the top of the library:
# My library This library was made as while following **a tutorial**. You can find more information on [the Charmhub website]([https://charmhub.io](https://charmhub.io)).
Note that the section supports markdown.
Explain each function using Google Python Docstring.
def function(): """This sentence is a summary of the function. This section gives more details about the function and what it does. In this case the function returns foo. Returns: A string containing "foo" """ return "foo" class Example: """A one sentence summary of the class. This section gives more details about the class and what it does. Arguments: foo (int): the argument foo bar (str): the argument bar Attributes: foo (int): the attribute foo bar (str): the attribute bar """ def __init__(self, foo, bar): self.foo = foo self.bar = bar def info(self, add=1): """Return foo plus add. This function adds add to foo Arguments: add (int, optional): The number to add to foo. Defaults to 1. Returns: self.foo plus add """ return add + self.foo
Publish and share
In a terminal, go into the charm project and run the command:
charmcraft publish-lib LIBRARY_CLASS, where LIBRARY_CLASS is the python module path of the library.
To share it with developers:
- Access your charm page on charmhub.io.
- Go on the library tab.
- You should see on the left navigation your library
- Click on it
- You can now share this URL with other charm developers
Libraries are a great way to help other authors to write charms that can relate to yours. Be sure to review your library to make sure it looks as intended and feel free to share the library URL with other charm developers.