1.. 2 Copyright (C) 2014-2018 Red Hat, Inc. 3 4 This copyrighted material is made available to anyone wishing to use, 5 modify, copy, or redistribute it subject to the terms and conditions of 6 the GNU General Public License v.2, or (at your option) any later version. 7 This program is distributed in the hope that it will be useful, but WITHOUT 8 ANY WARRANTY expressed or implied, including the implied warranties of 9 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 10 Public License for more details. You should have received a copy of the 11 GNU General Public License along with this program; if not, write to the 12 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 13 02110-1301, USA. Any Red Hat trademarks that are incorporated in the 14 source code or documentation are not subject to the GNU General Public 15 License and may only be used or replicated with the express permission of 16 Red Hat, Inc. 17 18=================================== 19 ``Base``---The centerpiece of DNF 20=================================== 21 22.. class:: dnf.Base 23 24 Instances of :class:`dnf.Base` are the central point of functionality supplied by DNF. An application will typically create a single instance of this class which it will keep for the runtime needed to accomplish its packaging tasks. Plugins are managed by DNF and get a reference to :class:`dnf.Base` object when they run. 25 26 :class:`.Base` instances are stateful objects holding references to various data sources and data sinks. To properly finalize and close off any handles the object may hold, client code should either call :meth:`.Base.close` when it has finished operations with the instance, or use the instance as a context manager. After the object has left the context, or its :meth:`.Base.close` has been called explicitly, it must not be used. :meth:`.Base.close` will delete all downloaded packages upon successful transaction. 27 28 .. attribute:: comps 29 30 Is ``None`` by default. Explicit load via :meth:`read_comps` initializes this attribute to a :class:`dnf.comps.Comps` instance. 31 32 .. attribute:: conf 33 34 An instance of :class:`dnf.conf.Conf`, concentrates all the different configuration options. :meth:`__init__` initializes this to usable defaults. 35 36 .. attribute:: goal 37 38 An instance of :class:`dnf.goal.Goal` that this :class:`Base<dnf.Base>` object is using. 39 40 .. attribute:: repos 41 42 A :class:`dnf.repodict.RepoDict` instance, this member object contains all the repositories available. 43 44 .. attribute:: sack 45 46 The :class:`Sack<dnf.sack.Sack>` that this :class:`Base<dnf.Base>` object is using. It needs to be explicitly initialized by :meth:`fill_sack`. 47 48 .. attribute:: transaction 49 50 A resolved transaction object, a :class:`dnf.transaction.Transaction` instance, or ``None`` if no transaction has been prepared yet. 51 52 .. method:: __init__() 53 54 Init an instance with a reasonable default configuration. The constructor takes no arguments. 55 56 .. method:: add_remote_rpms(path_list, strict=True, progress=None) 57 58 This function must be called before anything is added to the :attr:`goal`. Adds RPM files 59 in path_list to the :attr:`sack` and return the list of respective :class:`dnf.package.Package` 60 instances. Downloads the RPMs to a temporary file for each path if it is a remote URL. 61 Raises :exc:`IOError` if there are `IO` problems with files and `strict=True`. Raises 62 :exc:`dnf.exceptions.Error` if the :attr:`goal` is not empty. `progress`, if given, should be a 63 :class:`.DownloadProgress` instance which can be used to monitor the progress of the download. 64 65 .. method:: add_security_filters(cmp_type, types=(), advisory=(), bugzilla=(), cves=(), severity=()) 66 67 It modifies results of install, upgrade, and distrosync methods according to provided filters. 68 `cmp_type` - only 'eq' or 'gte' allowed 69 `types` - List or tuple with strings. Eg. `bugfix`, `enhancement`, `newpackage`, `security` 70 `advisory` - List or tuple with strings. Eg. `FEDORA-2201-123` 71 `bugzilla` - List or tuple with strings. Include packages that fix a Bugzilla ID, Eg. `123123`. 72 `cves` - List or tuple with strings. Include packages that fix a CVE (Common Vulnerabilities 73 and Exposures) ID. Eg. `CVE-2201-0123` 74 `severity` - List or tuple with strings. Includes packages that provide a fix for an issue 75 of the specified severity. 76 77 .. method:: reset_security_filters() 78 79 Reset all security filters 80 81 .. method:: close() 82 83 Close all external handles the object holds. This is called automatically via context manager mechanism if the instance is handled using the ``with`` statement. 84 85 .. method:: init_plugins([disabled_glob=None, cli=None]) 86 87 Initialize plugins. If you want to disable some plugins pass the list of their name patterns to 88 `disabled_glob`. When run from interactive script then also pass your :class:`dnf.cli.Cli` instance. 89 90 .. method:: pre_configure_plugins() 91 92 Configure plugins by running their pre_configure() method. It makes possible to change 93 variables before repo files and rpmDB are loaded. It also makes possible to create internal 94 repositories that will be affected by ``--disablerepo`` and ``--enablerepo``. 95 96 .. method:: configure_plugins() 97 98 Configure plugins by running their configure() method. 99 100 .. method:: fill_sack([load_system_repo=True, load_available_repos=True]) 101 102 Setup the package sack. If `load_system_repo` is ``True``, load information about packages in the local RPMDB into the sack. Else no package is considered installed during dependency solving. If `load_available_repos` is ``True``, load information about packages from the available repositories into the sack. 103 104 This operation will call :meth:`load() <dnf.repo.Repo.load>` for repos as necessary and can take a long time. Adding repositories or changing repositories' configuration does not affect the information within the sack until :meth:`fill_sack` has been called. 105 106 Before this method is invoked, the client application should setup any explicit configuration relevant to the operation. This will often be at least :attr:`conf.cachedir <.Conf.cachedir>` and the substitutions used in repository URLs. See :attr:`.Conf.substitutions`. 107 108 Throws `IOError` exception in case cached metadata could not be opened. 109 110 Example:: 111 112 #!/usr/bin/python3 113 import dnf 114 115 base = dnf.Base() 116 conf = base.conf 117 conf.cachedir = '/tmp/my_cache_dir' 118 conf.substitutions['releasever'] = '30' 119 conf.substitutions['basearch'] = 'x86_64' 120 121 base.repos.add_new_repo('my-repo', conf, 122 baseurl=["http://download.fedoraproject.org/pub/fedora/linux/releases/$releasever/Everything/$basearch/os/"]) 123 base.fill_sack() 124 125 print("Enabled repositories:") 126 for repo in base.repos.iter_enabled(): 127 print("id: {}".format(repo.id)) 128 print("baseurl: {}".format(repo.baseurl)) 129 130 .. method:: fill_sack_from_repos_in_cache(load_system_repo=True) 131 132 Prepare Sack and Goal objects and load all enabled repositories from cache only, it doesn't download anything and it doesn't check if metadata are expired. 133 To successfully load a repository cache it requires repomd.xml plus metadata (xml, yaml) or repomd.xml plus generated cache files (solv, solvx). 134 If there is not enough metadata given repo is either skipped or it throws a :exc:`dnf.exceptions.RepoError` exception depending on :attr:`dnf.conf.Conf.skip_if_unavailable` configuration. 135 136 All additional metadata are loaded if present but are not generally required. Note that some metadata like updateinfo.xml get processed into a solvx cache file and its sufficient to have either xml or solvx. Module metadata represented by modules.yaml are not processed therefore they are needed when they are defined in repomd.xml. 137 138 Example of loading all configured repositories from cache and printing available packages' names:: 139 140 #!/usr/bin/python3 141 import dnf 142 143 with dnf.Base() as base: 144 base.read_all_repos() 145 146 base.fill_sack_from_repos_in_cache(load_system_repo=False) 147 148 query = base.sack.query().available() 149 for pkg in query.run(): 150 print(pkg.name) 151 152 Example of loading a single repository and printing available packages' names without reading repository configuration:: 153 154 #!/usr/bin/python3 155 import dnf 156 157 with dnf.Base() as base: 158 repo = dnf.repo.Repo("rawhide", base.conf) 159 160 # Repository cache is also identified by its source therefore to find it you need to 161 # set metalink, mirrorlist or baseurl to the same value from which it was created. 162 repo.metalink = "https://mirrors.fedoraproject.org/metalink?repo=rawhide&arch=x86_64" 163 164 base.repos.add(repo) 165 166 base.fill_sack_from_repos_in_cache(load_system_repo=False) 167 168 query = base.sack.query().available() 169 for pkg in query.run(): 170 print(pkg.name) 171 172 .. method:: do_transaction([display]) 173 174 Perform the resolved transaction. Use the optional `display` object(s) to report the progress. `display` can be either an instance of a subclass of :class:`dnf.callback.TransactionProgress` or a sequence of such instances. Raise :exc:`dnf.exceptions.Error` or dnf.exceptions.TransactionCheckError. 175 176 .. method:: download_packages(pkglist, progress=None, callback_total=None) 177 178 Download packages in `pkglist` from remote repositories. Packages from local repositories or from the command line are not downloaded. `progress`, if given, should be a :class:`.DownloadProgress` and can be used by the caller to monitor the progress of the download. `callback_total` is a function accepting two parameters: total size of the downloaded content in bytes and time when the download process started, in seconds since the epoch. Raises :exc:`.DownloadError` if some packages failed to download. 179 180 .. method:: group_install(group_id, pkg_types, exclude=None, strict=True) 181 182 Mark group with corresponding `group_id` installed and mark the packages in the group for installation. Return the number of packages that the operation has marked for installation. `pkg_types` is a sequence of strings determining the kinds of packages to be installed, where the respective groups can be selected by including ``"mandatory"``, ``"default"`` or ``"optional"`` in it. If `exclude` is given, it has to be an iterable of package name glob patterns: :meth:`.group_install` will then not mark the respective packages for installation whenever possible. Parameter `strict` is a boolean indicating whether group packages that exist but are non-installable due to e.g. dependency issues should be skipped (False) or cause transaction to fail to resolve (True). 183 184 .. method:: group_remove(group_id) 185 186 Mark group with corresponding `group_id` not installed. All the packages marked as belonging to this group will be marked for removal. Return the number of packages marked for removal in this call. 187 188 .. method:: group_upgrade(group_id) 189 190 Upgrade group with corresponding `group_id`. If there has been packages added to the group's comps information since installing on the system, they will be marked for installation. Similarly, removed packages get marked for removal. The remaining packages in the group are marked for an upgrade. The operation respects the package types from the original installation of the group. 191 192 .. method:: environment_install(env_id, types, exclude=None, strict=True, exclude_groups=None) 193 194 Similar to :meth:`.group_install` but operates on environmental groups. `exclude_groups` is an iterable of group IDs that will not be marked as installed. 195 196 .. method:: environment_remove(env_id) 197 198 Similar to :meth:`.group_remove` but operates on environmental groups. 199 200 .. method:: environment_upgrade(env_id) 201 202 Similar to :meth:`.group_upgrade` but operates on environmental groups. 203 204 .. method:: read_all_repos() 205 206 Read repository configuration from the main configuration file specified by :attr:`dnf.conf.Conf.config_file_path` and any ``.repo`` files under :attr:`dnf.conf.Conf.reposdir`. All the repositories found this way are added to :attr:`~.Base.repos`. 207 208 .. method:: read_comps(arch_filter=False) 209 210 Read comps data from all the enabled repositories and initialize the :attr:`comps` object. If `arch_filter` is set to ``True``, the result is limited to system basearch. 211 212 .. method:: reset(\*\*kwargs) 213 214 Reset the state of different :class:`.Base` attributes. Selecting attributes to reset is controlled by passing the method keyword arguments set to ``True``. When called with no arguments the method has no effect. 215 216 =============== ================================================= 217 argument passed effect 218 =============== ================================================= 219 `goal=True` drop all the current :ref:`packaging requests <package_marking-label>` 220 `repos=True` drop the current repositories (see :attr:`.repos`). This won't 221 affect the package data already loaded into the :attr:`.sack`. 222 `sack=True` drop the current sack (see :attr:`.sack`) 223 =============== ================================================= 224 225 .. method:: resolve(allow_erasing=False) 226 227 Resolve the marked requirements and store the resulting :class:`dnf.transaction.Transaction` into :attr:`transaction`. Raise :exc:`dnf.exceptions.DepsolveError` on a depsolving error. Return ``True`` if the resolved transaction is non-empty. 228 229 Enabling `allow_erasing` lets the solver remove other packages while looking to fulfill the current packaging requests. For instance, this is used to allow the solver to remove dependants of a package being removed. 230 231 The exact operation of the solver further depends on the :attr:`dnf.conf.Conf.best` setting. 232 233 .. method:: update_cache(timer=False) 234 235 Downloads and caches in binary format metadata for all known repos. Tries to avoid downloading 236 whenever possible (e.g. when the local metadata hasn’t expired yet or when the metadata 237 timestamp hasn’t changed). 238 239 If 'timer' equals 'True', DNF becomes more resource-aware, meaning DNF will not do anything if 240 running on battery power and will terminate immediately if it’s too soon after the last 241 successful update_cache operation. 242 243 When the method is used after :meth:`fill_sack`, information about packages will not be updated. 244 245 .. method:: package_signature_check(pkg) 246 247 Verify the GPG signature of the given package object. 248 Returns tuple (`result`, `error_string`) where result is: 249 250 ======= ================================================= 251 result meaning 252 ======= ================================================= 253 0 GPG signature verifies ok or verification is not required. 254 1 GPG verification failed but installation of the right GPG key might help. 255 2 Fatal GPG verification error, give up. 256 ======= ================================================= 257 258 .. method:: package_import_key(pkg, askcb=None, fullaskcb=None) 259 260 Retrieve a key for a package. If needed, use the given callback to prompt whether the key should be imported. Raises :exc:`dnf.exceptions.Error` if there are errors retrieving the keys. 261 262 `askcb`: callback function to use to ask permission to import a key. The arguments `askcb` should take are the package object, the userid of the key, and the keyid 263 264 `fullaskcb`: callback function to use to ask permission to import a key. This differs from `askcb` in that it gets passed a dictionary so that we can expand the values passed. 265 266 Callback functions return ``True`` if the key should be imported, ``False`` otherwise. 267 268 .. _package_marking-label: 269 270 The :class:`.Base` class provides a number of methods to make packaging requests that can later be resolved and turned into a transaction. The `pkg_spec` argument some of them take must be a package specification recognized by :class:`dnf.subject.Subject`. If these methods fail to find suitable packages for the operation they raise a :exc:`~dnf.exceptions.MarkingError`. Note that successful completion of these methods does not necessarily imply that the desired transaction can be carried out (e.g. for dependency reasons). 271 272 .. method:: downgrade(pkg_spec) 273 274 Mark packages matching `pkg_spec` for downgrade. 275 276 .. method:: install(pkg_spec, reponame=None, strict=True, forms=None) 277 278 Mark packages matching `pkg_spec` for installation. 279 `reponame` can be a name of a repository or a list of repository names. If given, the selection of available packages is limited to packages from these repositories. If strict is set to False, the installation ignores packages with dependency solving problems. Parameter `forms` has the same meaning as in :meth:`dnf.subject.Subject.get_best_query`. 280 281 .. method:: package_downgrade(pkg, strict=False) 282 283 If `pkg` is a :class:`dnf.package.Package` in an available repository, mark the matching installed package for downgrade to `pkg`. If strict=False it ignores problems with dep-solving. 284 285 .. method:: package_install(pkg, strict=True) 286 287 Mark `pkg` (a :class:`dnf.package.Package` instance) for installation. Ignores package that is already installed. `strict` has the same meaning as in :meth:`install`. 288 289 .. method:: package_upgrade(pkg) 290 291 If `pkg` is a :class:`dnf.package.Package` in an available repository, mark the matching installed package for upgrade to `pkg`. 292 293 .. method:: autoremove() 294 295 Removes all 'leaf' packages from the system that were originally installed as dependencies of user-installed packages but which are no longer required by any such package. 296 297 .. method:: remove(pkg_spec, reponame=None, forms=None) 298 299 Mark packages matching `pkg_spec` for removal. `reponame` and `forms` have the same meaning as in :meth:`install`. 300 301 .. method:: upgrade(pkg_spec, reponame=None) 302 303 Mark packages matching `pkg_spec` for upgrade. `reponame` has the same meaning as in :meth:`install`. 304 305 .. method:: upgrade_all(reponame=None) 306 307 Mark all installed packages for an upgrade. `reponame` has the same meaning as in :meth:`install`. 308 309 .. method:: urlopen(url, repo=None, mode='w+b', \*\*kwargs): 310 311 Open the specified absolute `url` and return a file object which respects proxy setting even for non-repo downloads 312 313 .. method:: install_specs(install, exclude=None, reponame=None, strict=True, forms=None) 314 315 Provides unified way to mark packages, groups or modules for installation. The `install` and `exclude` arguments have to be iterables containing specifications of packages (e.g. 'dnf') or groups/modules (e.g. '\@core'). Specifications from the `exclude` list will not be marked for installation. The `reponame`, `strict` and `forms` parameters have the same meaning as in :meth:`install`. In case of errors the method raises :exc:`dnf.exceptions.MarkingErrors`. 316 317 Example to install two groups and a package:: 318 319 #!/usr/bin/python3 320 import dnf 321 import dnf.cli.progress 322 323 base = dnf.Base() 324 base.read_all_repos() 325 base.fill_sack() 326 327 base.install_specs(['acpi', '@Web Server', '@core']) 328 print("Resolving transaction...",) 329 base.resolve() 330 print("Downloading packages...") 331 progress = dnf.cli.progress.MultiFileProgressMeter() 332 base.download_packages(base.transaction.install_set, progress) 333 print("Installing...") 334 base.do_transaction() 335