.. _repolib_module: ======= RepoLib ======= The :ref:`repolib-module` module simplifies working with APT sources, especially those stored in the DEB822 format. It translates these sources into Python Objects for easy reading, parsing, and manipulation of them within Python programs. The program takes a user-defined sources filename and reads the contents, parsing it into a Python object which can then be iterated upon and which uses native data types where practicable. The :ref:`repolib-module` module also allows easy creation of new DEB822-style sources from user-supplied data. .. toctree:: :maxdepth: 1 :caption: RepoLib source/source ppa-module enums ================== ``repolib`` Module ================== The ``repolib`` Module is the main module for the package. It allows interfacing with the various Classes, Subclasses, and Functions provided by RepoLib. Module-level Attributes ======================= There are a couple of module-level attributes and functions provided directly in the module. .. _module-version ``VERSION`` ----------- repolib.VERSION Provides the current version of the library. .. _module_log_file_path ``LOG_FILE_PATH`` ----------------- repolib.LOG_FILE_PATH Stores the current path to the log file .. _module_log_level repolib.LOG_LEVEL Stores the current logging level. Note: Change this level using the :ref:`module_set_logging_level` function. .. _module_dirs Configuration directories ========================= repolib.KEYS_DIR repolib.SOURCES_DIR Stores the current :obj:`Pathlib.Path` pointing at the signing key and sources directories, respectively. Used for building path names and reading configuration. .. _module_distro_codename: DISTRO_CODENAME =============== repolib.DISTRO_CODENAME The current CODENAME field from LSB. If LSB is not available, it will default to ``linux``. .. _module_clean_chars CLEAN_CHARS =========== repolib.CLEAN_CHARS A ``dict`` which maps invalid characters for the :ref:`ident` attributes which cannot be used and their replacements. These limitations are based on invalid characters in unix-compatible filenames. .. _module_sources sources ======= repolib.sources A :obj:`dict` storing all current sources configured on the system. To save resources, this list is only loaded/parsed when :ref:`module_load_all_sources` is called, since many simple operations don't need the full list of currently-configured sources. .. _module_files files ===== repolib.files A :obj:`dict` containing any source file objects present in the configured sources dir (See :ref:`module_dirs`). This list is empty until :ref:`module_load_all_sources` is called, since many simple operations don't need the full list of currently-installed config files. .. _module_keys keys ==== repolib.keys A :obj`dict` containing any installed repository signing keys on the system. This list is empty until :ref:`module_load_all_sources` is called, since many simple operations don'tneed the full list of currently-installed keys. .. _module_compare_sources compare_sources() ----------------- repolib.compare_sources(source1, source2, excl_keys:list) -> bool Compares two sources based on arbitrary criteria. This looks at a given list of keys, and if the given keys between the two given sources are identical, returns True. Returns: :obj:`bool` `True` if the sources are identical, otherwise `False`. source1, source2 ^^^^^^^^^^^^^^^^ The two source objects to compare. excl_keys ^^^^^^^^^ :obj:`list` A list of DEB822key names to ignore when comparing. Even if these items don't match, this function still returns true if all other keys match. .. _module_combine_sources combine_sources() ----------------- repolib.combine_sources(source1, source2) -> None Copies all of the data in `source2` and adds it to `source1`. This avoids duplicating data and ensures that all of both sources' data are present in the unified source source1 ^^^^^^^ The source into which both sources should be merged source2 ^^^^^^^ The source from which to copy to `source1` .. _module_url_validator url_validator() --------------- repolib.url_validator(url: str) -> bool Validates a given URL and attempts to see if it's a valid Debian respository URL. Returns `True` if the URL appears to be valid and `False` if not. url ^^^ :obj:`str`The url to validate .. _module_validate_debline validate_debline() ================== repolib.util.validate_debline(line: str) -> bool Validate if the provided debline ``line`` is valid or not. Returns ``True`` if ``line`` is valid, otherwise ``False``. line ^^^^ :obj:`str` The line to validate .. _module_strip_hashes strip_hashes() -------------- repolib.strip_hashes(line: str) -> str Strips leading hash (`#`) characters from a line and returns the result. line ^^^^ :obj:`str` The line to strip .. _module_load_all_sources load_all_sources() ------------------ repolib.load_all_sources() -> None Loads all sources from the current system configuration. .. _module-set_testing set_testing() ------------- repolib.set_testing(testing: bool = True) -> None Enables or disables testing mode in Repolib When in testing mode, repolib will operate within a temporary directory rather tan on your live system configuration. This can be used for testing out changes to the program without worry about changes to the system config. It's also used for unit testing. testing ^^^^^^^ :obj:`bool` - Wether testing mode should be enabled (`True`) or not (`False`) Example ======= The following code as a Python program that creates in ``example.sources`` file in `/etc/apt/sources.list.d` with some sample data, then modifies the suites used by the source and prints it to the console, before finally saving the new, modified source to disk:: import repolib source = repolib.Source() file = repolib.SourceFile(name='example') source.ident = 'example-source' source.name = 'Example Source' source.types = [repolib.SourceType.BINARY] source.uris = ['http://example.com/software'] source.suites = ['focal'] source.components = ['main'] file.add_source(source) print(source.ui) file.save() When run with the appropriate arguments, it prints the contents of the source to console and then saves a new ``example.sources`` file:: $ example-source: Name: Example Source Enabled: yes Types: deb URIs: http://example.com/software Suites: focal Components: main $ ls -la /etc/apt/sources.list.d/example.sources -rw-r--r-- 1 root root 159 May 1 15:21 /etc/apt/sources.list.d/example.sources Below is a walkthrough of this example. Creating Source and File Objects -------------------------------- The first step in using :ref:`repolib_module` is creating :ref:`source_object` and :ref:`file_object`:: source = repolib.Source() file = repolib.SourceFile(name='example') The :ref:`source_object` will hold all of the information for the source to be created. The :ref:`file_object` represents the output file on disk, and allows for advanced usage like multiple sources per file. Adding and Manipulating Data ---------------------------- The :ref:`source_object` contains attributes which describe the connfiguration aspects of the source required to fetch and install software. Generally, these attributes are lists of strings which describe different aspects of the source. They can be set or retrieved like any other attributes:: source.uris = ['http://example.com/software'] source.suites = ['focal'] This will add a ``focal`` suite to our source and add a URI from which to download package lists. :ref:`source_object` also presents a dict-like interface for setting and getting configuration data. Key names are case-insensitive and their order within the object are preserved. Adding the Source to the File ----------------------------- Before the :ref:`source_object` can be saved, it needs to be added to a :ref:`file_object`:: file.add_source(source) This will add `source` to the `file`'s lists of sources, as well as setting the `source`'s file attribute to `file`. Saving Data to Disk ------------------- Once a source has the correct data and has been added to a file object, it can be saved into the system configuration using :ref:`file-save`:: file.save() When called, this writes the sources stored in the file to disk. This does not destroy the object, so that it may be further manipulated by the program. .. note:: While data within the source or file objects can be manipulated after calling :ref:`file-save`, any subsequent changes will not be automatically written to disk as well. The :ref:`file-save` method must be called to commit changes to disk. .. _source_object: