prefs
Module to hold module-global variables as preferences.
Upon import, prefs attempts to import a prefs.json
file from the default location (see prefs.init()
).
Prefs are then accessed with prefs.get()
and prefs.set()
functions. After initialization, if a pref if set
,
it is stored in the prefs.json
file – prefs are semi-durable and persist across sessions.
When attempting to get a pref that is not set, prefs.get()
will first try to find a default value (set in
_PREFS
, and if none is found return None
– accordingly
no prefs should be intentionally set to None, as it signifies that the pref is not set.
Prefs are thread- and process-safe, as they are stored and served by a multiprocessing.Manager
object.
prefs.json
is typically generated by running autopilot.setup.setup_autopilot
, though you can freestyle it
if you are so daring.
The ``HARDWARE`` pref is a little special. It specifies how each of the hardware
components connected to the system
is configured. It is a dictionary with this general structure:
'HARDWARE': {
'GROUP': {
'ID': {
'hardware_arg': 'val'
}
}
}
where there are user-named 'GROUPS'
of hardware objects, like 'LEDS'
, etc. Within a group, each object has its
'ID'
(passed as the name
argument to the hardware initialization method) which allows it to be identified from
the other components in the group. The intention of this structure is to allow multiple categories of hardware objects
to be parameterized and used separately, even though they might be the same object type. Eg. we may have three LEDs
in our nosepokes, but also have an LED that serves at the arena light. If we wanted to write a command that turns off all
LEDs, we would have to explicitly specify their IDs, making it difficult to re-use very common hardware command patterns
within tasks. There are obvious drawbacks to this scheme – clunky, ambiguous, etc. and will be deprecated as parameterization
continues to congeal across the library.
The class that each element is used with is determined by the Task.HARDWARE
dictionary. Specifically, the Task.init_hardware()
method does something like:
self.hardware['GROUP']['ID'] = self.HARDWARE['GROUP']['ID'](**prefs.get('HARDWARE')['GROUP']['ID'])
Warning
These are not hard coded prefs. _DEFAULTS
populates the default values for prefs, but local prefs are
always restored from and saved to prefs.json
. If you’re editing this file and things aren’t changing,
you’re in the wrong place!
This iteration of prefs with respect to work done on the People’s Ventilator Project
If a pref has a string for a 'deprecation'
field in prefs._DEFAULTS
, a FutureWarning
will be raised with the string given as the message
Classes:
|
Enum that lists available scopes and groups for prefs |
Prefs common to all autopilot agents |
|
Directories and paths that define the contents of the user directory. |
|
Abstract prefs class for prefs that are specific to agents |
|
Prefs for the |
|
Prefs for the |
|
Prefs to configure the audio server |
|
Abstract class for hardware objects, |
Functions:
|
Get a pref! |
|
Set a pref! |
|
Dump prefs into the |
|
Initialize prefs on autopilot start. |
|
Add a pref after init |
|
Get the git hash of the current commit. |
|
|
|
Mostly for use in testing, clear loaded prefs (without deleting prefs.json) |
- class Scopes(value)[source]
Bases:
enum.Enum
Enum that lists available scopes and groups for prefs
Scope can be an agent type, common (for everyone), or specify some subgroup of prefs that should be presented together (like directories)
COMMON = All Agents DIRECTORY = Prefs group for specifying directory structure TERMINAL = prefs for Terminal Agents Pilot = Prefs for Pilot agents LINEAGE = prefs for networking lineage (until networking becomes more elegant ;) AUDIO = Prefs for configuring the Jackd audio server
Attributes:
All agents
Prefs specific to Terminal Agents
Prefs specific to Pilot Agents
Directory structure
Prefs for coordinating network between pilots and children
Audio prefs...
- COMMON = 1
All agents
- TERMINAL = 2
Prefs specific to Terminal Agents
- PILOT = 3
Prefs specific to Pilot Agents
- DIRECTORY = 4
Directory structure
- LINEAGE = 5
Prefs for coordinating network between pilots and children
- AUDIO = 6
Audio prefs…
- pydantic settings Common_Prefs[source]
Bases:
autopilot.root.Autopilot_Pref
Prefs common to all autopilot agents
Show JSON schema
{ "title": "Common_Prefs", "description": "Prefs common to all autopilot agents", "type": "object", "properties": {}, "additionalProperties": false }
- Config
alias_generator: function = <function no_underscore_all_caps at 0x7fa93f9adee0>
env_prefix: str = AUTOPILOT_
- pydantic settings Directory_Prefs[source]
Bases:
autopilot.root.Autopilot_Pref
Directories and paths that define the contents of the user directory.
In general, all paths should be beneath the USER_DIR
Show JSON schema
{ "title": "Directory_Prefs", "description": "Directories and paths that define the contents of the user directory.\n\nIn general, all paths should be beneath the `USER_DIR`", "type": "object", "properties": {}, "additionalProperties": false }
- Config
env_prefix: str = AUTOPILOT_DIRECTORY_
- pydantic settings Agent_Prefs[source]
Bases:
autopilot.root.Autopilot_Pref
Abstract prefs class for prefs that are specific to agents
Show JSON schema
{ "title": "Agent_Prefs", "description": "Abstract prefs class for prefs that are specific to agents", "type": "object", "properties": {}, "additionalProperties": false }
- Config
alias_generator: function = <function no_underscore_all_caps at 0x7fa93f9adee0>
env_prefix: str = AUTOPILOT_
- pydantic settings Terminal_Prefs[source]
Bases:
autopilot.prefs.Agent_Prefs
Prefs for the
Terminal
Show JSON schema
{ "title": "Terminal_Prefs", "description": "Prefs for the :class:`~autopilot.agents.terminal.Terminal`", "type": "object", "properties": {}, "additionalProperties": false }
- Config
env_prefix: str = AUTOPILOT_TERMINAL_
- pydantic settings Pilot_Prefs[source]
Bases:
autopilot.prefs.Agent_Prefs
Prefs for the
Pilot
Show JSON schema
{ "title": "Pilot_Prefs", "description": "Prefs for the :class:`~autopilot.agents.pilot.Pilot`", "type": "object", "properties": {}, "additionalProperties": false }
- Config
env_prefix: str = AUTOPILOT_PILOT_
- pydantic settings Audio_Prefs[source]
Bases:
autopilot.root.Autopilot_Pref
Prefs to configure the audio server
Show JSON schema
{ "title": "Audio_Prefs", "description": "Prefs to configure the audio server", "type": "object", "properties": {}, "additionalProperties": false }
- Config
alias_generator: function = <function no_underscore_all_caps at 0x7fa93f9adee0>
env_prefix: str = AUTOPILOT_
- pydantic settings Hardware_Pref[source]
Bases:
autopilot.root.Autopilot_Pref
Abstract class for hardware objects,
Show JSON schema
{ "title": "Hardware_Pref", "description": "Abstract class for hardware objects,", "type": "object", "properties": {}, "additionalProperties": false }
- Config
alias_generator: function = <function no_underscore_all_caps at 0x7fa93f9adee0>
env_prefix: str = AUTOPILOT_
- get(key: Optional[str] = None)[source]
Get a pref!
If a value for the given
key
can’t be found, prefs will attempt to- Parameters
key (str, None) – get pref of specific
key
, ifNone
, return all prefs- Returns
value of pref (type variable!), or
None
if no pref of passedkey
- set(key: str, val)[source]
Set a pref!
Note
Whenever a pref is set, the prefs file is automatically updated – prefs are system-durable!!
(specifically, whenever the module-level
_INITIALIZED
value is set to True, prefs are saved to file to avoid overwriting before loading)- Parameters
key (str) – Name of pref to set
val – Value of pref to set (prefs are not type validated against default types)
- save_prefs(prefs_fn: Optional[str] = None)[source]
Dump prefs into the
prefs_fn
.json file- Parameters
prefs_fn (str, None) – if provided, pathname to
prefs.json
otherwise resolveprefs.json
according theto the normal methods….
- init(fn=None)[source]
Initialize prefs on autopilot start.
If passed dict of prefs or location of prefs.json, load and use that
Otherwise
Look for the autopilot wayfinder
~/.autopilot
file that tells us where the user directory islook in default location
~/autopilot/prefs.json
Todo
This function may be deprecated in the future – in its current form it serves to allow the sorta janky launch methods in the headers/footers of autopilot/agents/pilot.py and autopilot/agents/terminal.py that will eventually be transformed into a unified agent framework to make launching easier. Ideally one would be able to just import prefs without having to explicitly initialize it, but we need to formalize the full launch process before we make the full lurch to that model.
- Parameters
fn (str, dict) – a path to prefs.json or a dictionary of preferences
- add(param, value)[source]
Add a pref after init
- Parameters
param (str) – Allcaps parameter name
value – Value of the pref
- git_version(repo_dir)[source]
Get the git hash of the current commit.
Stolen from numpy’s setup
and linked by ryanjdillon on SO
- Parameters
repo_dir (str) – directory of the git repository.
- Returns
git commit hash.
- Return type
unicode