Scruffy API¶
Config¶
Classes for loading and accessing configuration data.
-
class
scruffy.config.
Config
(data={}, defaults={}, root=None, path=None)¶ Config root node class. Just for convenience.
-
class
scruffy.config.
ConfigApplicator
(config)¶ Applies configs to other objects.
-
apply
(obj)¶ Apply the config to an object.
-
apply_to_str
(obj)¶ Apply the config to a string.
-
-
class
scruffy.config.
ConfigEnv
(prefix='SCRUFFY', *args, **kwargs)¶ Config based on based on environment variables.
-
class
scruffy.config.
ConfigFile
(path=None, defaults=None, load=False, apply_env=False, env_prefix='SCRUFFY', *args, **kwargs)¶ Config based on a loaded YAML or JSON file.
-
load
(reload=False)¶ Load the config and defaults from files.
-
prepare
()¶ Load the file when the Directory/Environment prepares us.
-
save
()¶ Save the config back to the config file.
-
-
class
scruffy.config.
ConfigNode
(data={}, defaults={}, root=None, path=None)¶ Represents a Scruffy config object.
Can be accessed as a dictionary, like this:
>>> config['top-level-section']['second-level-property']
Or as a dictionary with a key path, like this:
>>> config['top_level_section.second_level_property']
Or as an object, like this:
>>> config.top_level_section.second_level_property
-
reset
()¶ Reset the config to defaults.
-
to_dict
()¶ Generate a plain dictionary.
-
update
(data={}, options={})¶ Update the configuration with new data.
This can be passed either or both data and options.
options is a dict of keypath/value pairs like this (similar to CherryPy’s config mechanism:
>>> c.update(options={ ... 'server.port': 8080, ... 'server.host': 'localhost', ... 'admin.email': 'admin@lol' ... })
data is a dict of actual config data, like this:
>>> c.update(data={ ... 'server': { ... 'port': 8080, ... 'host': 'localhost' ... }, ... 'admin': { ... 'email': 'admin@lol' ... } ... })
-
-
scruffy.config.
update_dict
(target, source)¶ Recursively merge values from a nested dictionary into another nested dictionary.
For example:
>>> target = { ... 'thing': 123, ... 'thang': { ... 'a': 1, ... 'b': 2 ... } ... } >>> source = { ... 'thang': { ... 'a': 666, ... 'c': 777 ... } ... } >>> update_dict(target, source) >>> target { 'thing': 123, 'thang': { 'a': 666, 'b': 2, 'c': 777 } }
Environment¶
Classes for representing the encompassing environment in which your application runs.
-
class
scruffy.env.
Environment
(setup_logging=True, *args, **kwargs)¶ An environment in which to run a program
-
add
(**kwargs)¶ Add objects to the environment.
-
cleanup
()¶ Clean up the environment
-
find_config
(children)¶ Find a config in our children so we can fill in variables in our other children with its data.
-
File¶
Classes for representing and performing operations on files and directories.
-
class
scruffy.file.
Directory
(path=None, base=None, create=True, cleanup=False, parent=None, **kwargs)¶ A filesystem directory.
A Scruffy Environment usually encompasses a number of these. For example, the main Directory object may represent ~/.myproject.
>>> d = Directory({ ... path='~/.myproject', ... create=True, ... cleanup=False, ... children=[ ... ... ... ] ... })
path can be either a string representing the path to the directory, or a nested Directory object. If a Directory object is passed as the path its path will be requested instead. This is so Directory objects can be wrapped in others to inherit their properties.
-
add
(*args, **kwargs)¶ Add objects to the directory.
-
apply_config
(applicator)¶ Replace any config tokens with values from the config.
-
cleanup
()¶ Clean up children and remove the directory.
Directory will only be removed if the cleanup flag is set.
-
create
()¶ Create the directory.
Directory will only be created if the create flag is set.
-
exists
¶ Check if the directory exists.
-
list
()¶ List the contents of the directory.
-
path
¶ Return the path to this directory.
-
path_to
(path)¶ Find the path to something inside this directory.
-
prepare
()¶ Prepare the Directory for use in an Environment.
This will create the directory if the create flag is set.
-
read
(filename)¶ Read a file from the directory.
-
remove
(recursive=True, ignore_error=True)¶ Remove the directory.
-
write
(filename, data, mode='w')¶ Write to a file in the directory.
-
-
class
scruffy.file.
File
(path=None, create=False, cleanup=False, parent=None)¶ Represents a file that may or may not exist on the filesystem.
Usually encapsulated by a Directory or an Environment.
-
apply_config
(applicator)¶ Replace any config tokens in the file’s path with values from the config.
-
cleanup
()¶ Clean up the file after use in an Environment or Directory.
This will remove the file if the cleanup flag is set.
-
content
¶ Property for the content of the file.
-
create
()¶ Create the file if it doesn’t already exist.
-
exists
¶ Whether or not the file exists.
-
ext
¶ Get the file’s extension.
-
name
¶ Get the file name.
-
path
¶ Get the path to the file relative to its parent.
-
prepare
()¶ Prepare the file for use in an Environment or Directory.
This will create the file if the create flag is set.
-
read
()¶ Read and return the contents of the file.
-
remove
()¶ Remove the file if it exists.
-
write
(data, mode='w')¶ Write data to the file.
data is the data to write mode is the mode argument to pass to open()
-
-
class
scruffy.file.
JsonFile
(path=None, create=False, cleanup=False, parent=None)¶ A json file that is parsed into a dictionary.
-
class
scruffy.file.
LockFile
(*args, **kwargs)¶ A file that is automatically created and cleaned up.
-
create
()¶ Create the file.
If the file already exists an exception will be raised
-
-
class
scruffy.file.
LogFile
(path=None, logger=None, loggers=[], formatter={}, format=None, *args, **kwargs)¶ A log file to configure with Python’s logging module.
-
configure
()¶ Configure the Python logging module for this file.
-
prepare
()¶ Configure the log file.
-
-
class
scruffy.file.
PackageDirectory
(path=None, package=None, *args, **kwargs)¶ A filesystem directory relative to a Python package.
-
class
scruffy.file.
PackageFile
(path=None, create=False, cleanup=False, parent=None, package=None)¶ A file whose path is relative to a Python package.
Plugin¶
Classes for representing and loading plugins.
-
class
scruffy.plugin.
Plugin
¶ Top-level plugin class, using the PluginRegistry metaclass.
All plugin modules must implement a single subclass of this class. This subclass will be the class collected in the PluginRegistry, and should contain references to any other resources required within the module.
-
class
scruffy.plugin.
PluginManager
¶ Loads plugins which are automatically registered with the PluginRegistry class, and provides an interface to the plugin collection.
-
load_plugins
(directory)¶ Loads plugins from the specified directory.
directory is the full path to a directory containing python modules which each contain a subclass of the Plugin class.
There is no criteria for a valid plugin at this level - any python module found in the directory will be loaded. Only modules that implement a subclass of the Plugin class above will be collected.
The directory will be traversed recursively.
-
-
class
scruffy.plugin.
PluginRegistry
(name, bases, attrs)¶ Metaclass that registers any classes using it in the plugins array
State¶
Classes for storing a program’s state.
-
class
scruffy.state.
State
(path=None)¶ A program’s state.
Contains a dictionary that can be periodically saved and restored at startup.
Maybe later this will be subclassed with database connectors and whatnot, but for now it’ll just save to a yaml file.
-
cleanup
()¶ Clean up the saved state.
-
load
()¶ Load a saved state file.
-
save
()¶ Save the state to a file.
-