As the pre 4.7.0 API was fundamentally tied to module-level globals, we had to change the internal enstaller API in a fundamental way. This guide explains how to transition to the new API.
enstaller.config
The enstaller.config module has been completely revamped:
- The main API is now the :py
~enstaller.config.Configuration
class. Multiple instances of this class can coexist in the same process (though one may need to be careful about keyring-related interactions). - Most individual methods of the module have been removed, and the information need to be accessed through the configuration object instead.
The most common way to create a configuration is to start from an existing configuration file:
config = Configuration.from_file(filename)
print(config.use_webservice)
One can also create a configuration from the default location:
config = Configuration._from_legacy_locations()
This API may be revised as we change the location logic (the current logic made sense for an EPD-like setup, but does not anymore with virtualenvs).
Note
this method will fail if no .enstaller4rc is found. To create a default enstaller4rc, you should use the write_default_config
function first:
filename = ... if not os.path.exists(filename): write_default_config(filename)
config = Configuration.from_file(filename)
As the get_auth function was implicitely sharing global state, it has been removed. Instead of:
# Obsolete
from enstaller.config import get_auth
print(get_auth())
one should use:
config = Configuration._from_legacy_locations()
print(config.auth)
Note
the authentication may not be setup, in which case config.auth may return an invalid configration. To check whether the authentication is valid, use the is_auth_configured property:
config = Configuration._from_legacy_locations() if config.is_auth_configured: print(config.auth)
Enstaller does not use keyring anymore to hold password securely. Instead, the password is now always stored insecurely in the EPD_auth setting inside .enstaller4rc.
For backward compatibility, enpkg will convert password stored in the keyring back into .enstaller4rc automatically. To avoid keyring issues, keyring is bundled inside enstaller.
We advise not to change authentication directly in .enstaller4rc, as changing configuration file is user-hostile. Instead, applications using enstaller library should store the authentication themselves, and set it up inside the Configuration object through the :py~enstaller.config.Configuration.set_auth
method.
The private methods Configuration._change_auth and Configuration._checked_change_auth are there for convenience, but their usage is discouraged.
Note
while keeping the password in clear in insecure, this is actually more secure as enstaller would before implicitely change from clear to secure and vice et versa depending on whether keyring was available to enstaller. The midterm solution is to use token-based authentication and never store password, but this will need some support server-side before being deployed.
The following functions have been removed:
- clear_auth: obsolete with keyring removal
- clear_cache: there is no configuration state anymore, juse use a new
Configuration
instance. - get_repository_cache: use
Configuration.repository_cache
attribute - get: use correponding
Configuration
attributes instead - read: use
Configuration
instance and its attributes - web_auth: use
authenticate
instead - write: use the
~Configuration.write
method instead
Most of the store-related functionalities are now available through the :py~enstaller.repository.Repository
class. See repository-guide-label
for more information.