Dev guide for transitioning to 4.7.0 API¶
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.
Configuration¶
The enstaller.config module has been completely revamped:
- The main API is now the
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.
Creating configuration instances¶
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)
Replacing get_auth¶
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)
Changing authentication¶
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
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.
Removed config module functions¶
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
write()
method instead
Repositories and package metadata¶
Most of the store-related functionalities are now available through the
Repository
class. See
repository-guide-label for more information.