282 lines
7.7 KiB
ReStructuredText
282 lines
7.7 KiB
ReStructuredText
|
.. _source_object:
|
||
|
|
|
||
|
|
=============
|
||
|
|
Source object
|
||
|
|
=============
|
||
|
|
|
||
|
|
The Source object is the base class for all of the sources used within RepoLib.
|
||
|
|
The Source class itself is a subclass of the deb822() class from the Python
|
||
|
|
Debian module, which provides a dict-like interface for setting data as well as
|
||
|
|
several methods for dumping data to files and other helpful functions.
|
||
|
|
|
||
|
|
.. toctree::
|
||
|
|
:maxdepth: 2
|
||
|
|
:caption: Source
|
||
|
|
|
||
|
|
deb
|
||
|
|
legacy-deb
|
||
|
|
ppa-object
|
||
|
|
system
|
||
|
|
|
||
|
|
class repolib.Source (file=None)
|
||
|
|
Create a new :ref:`source_object`.
|
||
|
|
|
||
|
|
|
||
|
|
The Source object has the following attributes:
|
||
|
|
|
||
|
|
* :ref:`ident` - The system-identifier to use for this source.
|
||
|
|
* :ref:`name` - The human-readable name of the source. (default: '')
|
||
|
|
* :ref:`enabled` - Whether the source is enabled or not at creation.
|
||
|
|
(default: True)
|
||
|
|
* :ref:`types` - A list of the types that the source should use.
|
||
|
|
(default: [])
|
||
|
|
* :ref:`uris` - A list of URIs from which to fetch software or check for
|
||
|
|
updates. (default: [])
|
||
|
|
* :ref:`suites` - Suites in which to narrow available software. (default:
|
||
|
|
[])
|
||
|
|
* :ref:`components` - Components of the source repository to enable.
|
||
|
|
(default: [])
|
||
|
|
* :ref:`signed_by` - The path to the signing key for this source
|
||
|
|
* :ref:`file` - The :ref:`file_object` for this source
|
||
|
|
* :ref:`key` - The :ref:`key_object` for this source.
|
||
|
|
* :ref:`twin_source`: - This source should be saved with both binary and
|
||
|
|
source code types enabled.
|
||
|
|
|
||
|
|
The following decribe how each of these are used.
|
||
|
|
|
||
|
|
.. _ident:
|
||
|
|
|
||
|
|
ident
|
||
|
|
-----
|
||
|
|
|
||
|
|
The ``ident`` is the system-identifier for this source. This determines the
|
||
|
|
filename the source will use on-disk as well as the way to specify a source to
|
||
|
|
load.
|
||
|
|
|
||
|
|
.. _name:
|
||
|
|
|
||
|
|
name
|
||
|
|
----
|
||
|
|
|
||
|
|
This is a human-readable and nicely-formatted name to help a user recognize
|
||
|
|
what this source is. Any unicode character is allowed in this field. If a
|
||
|
|
source is opened which doesn't have a name field, the filename will be used.
|
||
|
|
|
||
|
|
:ref:`name` is a string value, set to ``''`` by default. If there is no name in
|
||
|
|
a loaded source, it will be set to the same as the filename (minus the
|
||
|
|
extension).
|
||
|
|
|
||
|
|
This field maps to the ``X-Repolib-Name:`` field in the .sources file, which
|
||
|
|
is ignored by Apt and other standards-compliant sources parsers.
|
||
|
|
|
||
|
|
.. _enabled:
|
||
|
|
|
||
|
|
enabled
|
||
|
|
-------
|
||
|
|
|
||
|
|
Apt sources can be disbaled without removing them entirely from the system. A
|
||
|
|
disabled source is excluded from updates and new software installs, but it can
|
||
|
|
be easily re-enabled at any time. It defaults to ``True``.
|
||
|
|
|
||
|
|
This field maps to the ``Enabled:`` field in the .sources file. This is optional
|
||
|
|
per the DEB822 standard, however if set to anything other than ``no``, the
|
||
|
|
source is considered enabled.
|
||
|
|
|
||
|
|
.. _types:
|
||
|
|
|
||
|
|
types
|
||
|
|
-----
|
||
|
|
|
||
|
|
Debian archives may contain either binary packages or source code packages, and
|
||
|
|
this value specifies which of those Apt should look for in the source. ``deb``
|
||
|
|
is used to look for binary packages, while ``deb-src`` looks for source code
|
||
|
|
packages. RepoLib stores this value as a list of :ref:`aptsourcetype-enum`s, and
|
||
|
|
defaults to ``[AptSourceType.BINARY]``.
|
||
|
|
|
||
|
|
This field maps to the ``Types:`` field in the sources file.
|
||
|
|
|
||
|
|
.. _uris:
|
||
|
|
|
||
|
|
uris
|
||
|
|
----
|
||
|
|
|
||
|
|
A list of string values describing the URIs from which to fetch package lists
|
||
|
|
and software for updates and installs. The currently recognized URI types are:
|
||
|
|
|
||
|
|
* file
|
||
|
|
* cdrom
|
||
|
|
* http
|
||
|
|
* ftp
|
||
|
|
* copy
|
||
|
|
* rsh
|
||
|
|
* ssh
|
||
|
|
|
||
|
|
DEB822 sources may directly contain an arbitrary number of URIs. Legacy sources
|
||
|
|
may also have multiple URIs; however, these require writing a new deb line for
|
||
|
|
each URI as the one-line format only allows a single URI per source.
|
||
|
|
|
||
|
|
.. note::
|
||
|
|
Although these are the currently-recognized official URI types, Apt can be
|
||
|
|
extended with additional URI schemes through extension packages. Thus it is
|
||
|
|
**not** recommended to parse URIs by type and instead rely on user input
|
||
|
|
being correct and to throw exceptions when that isn't the case.
|
||
|
|
|
||
|
|
.. _suites:
|
||
|
|
|
||
|
|
suites
|
||
|
|
------
|
||
|
|
|
||
|
|
The Suite, also known as the **distribution** specifies a subdirectory of the
|
||
|
|
main archive root in which to look for software. This is typically used to
|
||
|
|
differentiate versions for the same OS, e.g. ``disco`` or ``cosmic`` for Ubuntu,
|
||
|
|
or ``squeeze`` and ``unstable`` for Debian.
|
||
|
|
|
||
|
|
DEB822 Sources allow specifying an arbitrary number of suites. One-line sources
|
||
|
|
also support multiple suites, but require an additional repo line for each as
|
||
|
|
the one-line format only allows a single suite for each source.
|
||
|
|
|
||
|
|
This value maps to the ``Suites:`` field in the sources file.
|
||
|
|
|
||
|
|
.. _components:
|
||
|
|
|
||
|
|
components
|
||
|
|
----------
|
||
|
|
|
||
|
|
This value is a list of strings describing the enabled distro components to
|
||
|
|
download software from. Common values include ``main``, ``restricted``,
|
||
|
|
``nonfree``, etc.
|
||
|
|
|
||
|
|
.. _signed_by
|
||
|
|
|
||
|
|
signed_by
|
||
|
|
---------
|
||
|
|
The path to the keyring containing the signing key used to verify packages
|
||
|
|
downloaded from this repository. This should generally match the
|
||
|
|
:ref:`key-path` attribute for this source's :ref:`key` object.
|
||
|
|
|
||
|
|
.. _source-file
|
||
|
|
|
||
|
|
file
|
||
|
|
----
|
||
|
|
The :ref:`file_object` for the file which contains this source.
|
||
|
|
|
||
|
|
.. _key
|
||
|
|
|
||
|
|
key
|
||
|
|
---
|
||
|
|
The :ref:`key_object` for this source.
|
||
|
|
|
||
|
|
=======
|
||
|
|
Methods
|
||
|
|
=======
|
||
|
|
|
||
|
|
|
||
|
|
.. _get_description
|
||
|
|
|
||
|
|
Source.get_description() -> str
|
||
|
|
Returns a :obj:`str` containing a UI-compatible description of the source.
|
||
|
|
|
||
|
|
.. _reset_values:
|
||
|
|
|
||
|
|
reset_values()
|
||
|
|
-------------
|
||
|
|
|
||
|
|
Source.reset_values()
|
||
|
|
Initializes the Source's attributes with default data in-order. This is
|
||
|
|
recommended to ensure that the fields in the underlying deb822 Dict are
|
||
|
|
in order and correctly capitalized.
|
||
|
|
|
||
|
|
.. _load_from_data
|
||
|
|
|
||
|
|
load_from_data()
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Source.load_from_data(data: list) -> None
|
||
|
|
Loads configuration information from a list of data, rather than using
|
||
|
|
manual entry. The data can either be a list of strings with DEB822 data, or
|
||
|
|
a single-element list containing a one-line legacy line.
|
||
|
|
|
||
|
|
data
|
||
|
|
^^^^
|
||
|
|
The data load load into the source. If this contains a legacy-format one-line
|
||
|
|
repository, it must be a single-element list. Otherwise, it should contain a
|
||
|
|
list of strings, each being a line from a DEB822 configuration.
|
||
|
|
|
||
|
|
.. _generate_default_ident
|
||
|
|
|
||
|
|
generate_default_ident()
|
||
|
|
------------------------
|
||
|
|
|
||
|
|
Source.generate_default_ident(prefix: str = '') -> str
|
||
|
|
Generates a suitable default ident, optionally with a prefix, and sets it.
|
||
|
|
The generated ident is also returned for processing convenience.
|
||
|
|
|
||
|
|
prefix
|
||
|
|
^^^^^^
|
||
|
|
The prefix to prepend to the ident.
|
||
|
|
|
||
|
|
.. _generate_default_name
|
||
|
|
|
||
|
|
generate_default_name()
|
||
|
|
_______________________
|
||
|
|
|
||
|
|
Source.generate_default_name() ->
|
||
|
|
Generates a default name for the source and sets it. The generated name is
|
||
|
|
also returned for convenience.
|
||
|
|
|
||
|
|
.. _load_key
|
||
|
|
|
||
|
|
load_key()
|
||
|
|
__________
|
||
|
|
|
||
|
|
Source.load_key(ignore_errors: bool = True) -> None
|
||
|
|
Finds the signing key for this source spefified in :ref:`signed_by` and
|
||
|
|
loads a :ref:`key_object` for it.
|
||
|
|
|
||
|
|
ignore_errors
|
||
|
|
^^^^^^^^^^^^^
|
||
|
|
If `False`, raise a :ref:`exc_sourceerror` if the key can't be loaded or doesn't
|
||
|
|
exist.
|
||
|
|
|
||
|
|
.. _source_save
|
||
|
|
|
||
|
|
save()
|
||
|
|
------
|
||
|
|
|
||
|
|
Source.save()
|
||
|
|
Proxy method for the :ref:`file-save` method for this source's
|
||
|
|
:ref:`file_object`.
|
||
|
|
|
||
|
|
Output Properties
|
||
|
|
=================
|
||
|
|
|
||
|
|
There are three output properties which contain the current source data for
|
||
|
|
output in a variety of formats.
|
||
|
|
|
||
|
|
.. _source_deb822
|
||
|
|
|
||
|
|
deb822
|
||
|
|
------
|
||
|
|
|
||
|
|
Source.deb822
|
||
|
|
A representation of the source data as a DEB822-formatted string
|
||
|
|
|
||
|
|
.. _source_legacy
|
||
|
|
|
||
|
|
legacy
|
||
|
|
------
|
||
|
|
|
||
|
|
Source.legacy
|
||
|
|
A one-line formatted string of the source. It :ref:`twin_source` is ``True``,
|
||
|
|
then there will additionally be a ``deb-src`` line following the primary
|
||
|
|
line.
|
||
|
|
|
||
|
|
.. _source_ui
|
||
|
|
|
||
|
|
ui
|
||
|
|
--
|
||
|
|
|
||
|
|
Source.ui
|
||
|
|
A representation of the source with certain key names translated to better
|
||
|
|
represent their use in a UI for display to a user.
|