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:

`Scopes`(value)	Enum that lists available scopes and groups for prefs
`Common_Prefs`	Prefs common to all autopilot agents
`Directory_Prefs`	Directories and paths that define the contents of the user directory.
`Agent_Prefs`	Abstract prefs class for prefs that are specific to agents
`Terminal_Prefs`	Prefs for the `Terminal`
`Pilot_Prefs`	Prefs for the `Pilot`
`Audio_Prefs`	Prefs to configure the audio server
`Hardware_Pref`	Abstract class for hardware objects,

Functions:

`get`([key])	Get a pref!
`set`(key, val)	Set a pref!
`save_prefs`([prefs_fn])	Dump prefs into the `prefs_fn` .json file
`init`([fn])	Initialize prefs on autopilot start.
`add`(param, value)	Add a pref after init
`git_version`(repo_dir)	Get the git hash of the current commit.
`compute_calibration`([path, calibration, ...])	Parameters: path
`clear`()	Mostly for use in testing, clear loaded prefs (without deleting prefs.json)

class Scopes(value)[source]

Bases: 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:

`COMMON`	All agents
`TERMINAL`	Prefs specific to Terminal Agents
`PILOT`	Prefs specific to Pilot Agents
`DIRECTORY`	Directory structure
`LINEAGE`	Prefs for coordinating network between pilots and children
`AUDIO`	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_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 0x7f81f6934310>
env_prefix: str = AUTOPILOT_

pydantic settings Directory_Prefs[source]

Bases: 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_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 0x7f81f6934310>
env_prefix: str = AUTOPILOT_

pydantic settings Terminal_Prefs[source]

Bases: 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: 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_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 0x7f81f6934310>
env_prefix: str = AUTOPILOT_

pydantic settings Hardware_Pref[source]

Bases: 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 0x7f81f6934310>
env_prefix: str = AUTOPILOT_

get(key: str | None = 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, if None, return all prefs
Returns:: value of pref (type variable!), or None if no pref of passed key

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: str | None = None)[source]

Dump prefs into the prefs_fn .json file

Parameters:

prefs_fn (str, None) – if provided, pathname to prefs.json otherwise resolve prefs.json according the
to 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 is
look 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

compute_calibration(path=None, calibration=None, do_return=False)[source]

Parameters:

path
calibration
do_return

Returns:

clear()[source]

Mostly for use in testing, clear loaded prefs (without deleting prefs.json)

(though you will probably overwrite prefs.json if you clear and then set another pref so don’t use this except in testing probably)