owmeta_core.command module¶

This module defines the root of a high-level interface for owmeta_core, refered to as “OWM” (for the main class in the interface), “owm” (for the command line that wraps the interface), or “the command interface” in the documentation. Additional “sub-commands” may be defined which provide additional functionality.

If there is a suitable method in the high-level interface, it should generally be preferred to the lower-level interfaces for stability.

exception owmeta_core.command.AlreadyDisconnected(owm)[source]¶

Bases: Exception

Thrown when OWM is already disconnected but a request is made to disconnect again

exception owmeta_core.command.ConfigMissingException(key)[source]¶

Bases: GenericUserError

Thrown when a configuration key is missing

exception owmeta_core.command.DirtyProjectRepository[source]¶

Bases: Exception

Thrown when we’re about to commit, but the project repository has changes to the graphs such that it’s not safe to just re-serialize the indexed database over the graphs.

exception owmeta_core.command.InvalidGraphException[source]¶

Bases: GenericUserError

Thrown when a graph cannot be translated due to formatting errors

exception owmeta_core.command.NoConfigFileError(config_file_path)[source]¶

Bases: GenericUserError

Thrown when a project config file (e.g., ‘.owm/owm.conf’) cannot be found

exception owmeta_core.command.OWMDirMissingException[source]¶

Bases: GenericUserError

Thrown when the .owm directory is needed, but cannot be found

exception owmeta_core.command.StatementValidationError(statements)[source]¶

Bases: GenericUserError

Thrown in the case that a set of statements fails to validate

exception owmeta_core.command.UnreadableGraphException[source]¶

Bases: GenericUserError

Thrown when a graph cannot be read due to it being missing, the active user lacking permissions, etc.

class owmeta_core.command.NullContextRecord(node_index, statement)[source]¶

Bases: _NullContextRecord

Stored when the identifier for the context of an object we’re saving is None

Create new instance of _NullContextRecord(node_index, statement)

class owmeta_core.command.OWM(owmdir=None, non_interactive=False)[source]¶

Bases: object

High-level commands for working with owmeta data

Attributes

cleanup_manageratexit-like: An object to which functions can be registered and unregistered. To handle cleaning up connections that were not closed more directly (e.g., by calling disconnect)
progress_reportertqdm-like: A callable that presents some kind of progress to a user. Interface is a subset of the tqdm.tqdm object: the reporter must accept unit, miniters, file, and leave options, although what it does with those is unspecified. Additionally, for reporting progress on cloning a project, an optional interface is required.

add_graph(url=None, context=None, include_imports=True)[source]¶

Fetch a graph and add it to the local store.

Parameters

urlstr: The URL of the graph to fetch
contextrdflib.term.URIRef: If provided, only this context and, optionally, its imported graphs will be added.
include_importsbool: If True, imports of the named context will be included. Has no effect if context is None.

clone(url=None, update_existing_config=False, branch=None)[source]¶

Clone a data store

Parameters

urlstr: URL of the data store to clone
update_existing_configbool: If True, updates the existing config file to point to the given file for the store configuration
branchstr: Branch to checkout after cloning

commit(message, skip_serialization=False)[source]¶

Write the graph and configuration changes to the local repository

Parameters

messagestr: commit message
skip_serializationbool: If set, then skip graph serialization. Useful if you have manually changed the graph serialization or just want to commit changes to project configuration

connect(read_only=False, expect_cleanup=False)[source]¶

Create a connection to the project database.

Most commands will create their own connections where needed, but for multiple commands you’ll want to create one connection at the start. Multiple calls to this method can be made without calling disconnect on the resulting connection object, but only if read_only has the same value for all calls.

Read-only connections can only be made with the default stores: if you have configured your own store and you want the connection to be read-only, you must change the configuration to make it read-only before calling connect.

Parameters

read_onlybool: if True, the resulting connection will be read-only
expect_cleanupbool: if False, a warning will be issued if the cleanup_manager has to disconnect the connection

Returns

ProjectConnection: Usable as a context manager

declare(python_type, attributes=(), id=None)[source]¶

Create a new data object or update an existing one

Parameters

python_typestr: The path to the Python type for the object. Formatted like “full.module.path:ClassName”
attributesstr: Attributes to set on the object before saving
idstr: The identifier for the object

diff(color=False)[source]¶

Show differences between what’s in the working context set and what’s in the serializations

Parameters

colorbool: If set, then ANSI color escape codes will be incorporated into diff output. Default is to output without color.

disconnect()[source]¶

Destroy a connection to the project database

Should not be called if there is no active connection

fetch_graph(url)[source]¶

Fetch a graph

Parameters

urlstr: URL for the graph

get_default_context()[source]¶: Read the current target context for the repository

git(*args)[source]¶

Runs git commmands in the “.owm” directory

Parameters

*args: arguments to git

imports_context(context=None, user=False)[source]¶

Read or set current target imports context for the repository

Parameters

contextstr: The context to set
userbool: If set, set the context only for the current user. Has no effect for retrieving the context

init(update_existing_config=False, default_context_id=None)[source]¶

Makes a new graph store.

The configuration file will be created if it does not exist. If it does exist, the location of the database store will, by default, not be changed in that file

If not provided, some values will be prompted for, unless batch (non-interactive) mode is enabled. If batch mode is enabled, either an error will be returned or a default value will be used for missing options. Values which are required either in a prompt or as options are indicated as “Required” below.

Parameters

update_existing_configbool: If True, updates the existing config file to point to the given file for the store configuration
default_context_idstr: URI for the default context. Required

list_contexts()[source]¶: List contexts

regendb()[source]¶

Regenerates the indexed database from graph serializations.

Note that any uncommitted contents in the indexed database will be deleted.

retract(subject, property, object)[source]¶

Remove one or more statements

Parameters

subjectstr: The object which you want to say something about. optional
propertystr: The type of statement to make. optional
objectstr: The other object you want to say something about. optional

save(module, provider=None, context=None)[source]¶

Save the data in the given context

Saves the “mapped” classes declared in a module and saves the objects declared by the “provider” (see the argument’s description)

Parameters

modulestr: Name of the module housing the provider
providerstr: Name of the provider, a callble that accepts a context object and adds statements to it. Can be a “dotted” name indicating attribute accesses. Default is DEFAULT_SAVE_CALLABLE_NAME
contextstr: The target context. The default context is used

say(subject, property, object)[source]¶

Make a statement

Parameters

subjectstr: The object which you want to say something about
propertystr: The type of statement to make
objectstr: The other object you want to say something about

set_default_context(context, user=False)[source]¶

Set current default context for the repository

Parameters

contextstr: The context to set
userbool: If set, set the context only for the current user. Has no effect for retrieving the context

translate(translator, output_key=None, output_identifier=None, data_sources=(), named_data_sources=None)[source]¶

Do a translation with the named translator and inputs

Parameters

translatorstr: Translator identifier
output_keystr: Output key. Used for generating the output’s identifier. Exclusive with output_identifier
output_identifierstr: Output identifier. Exclusive with output_key
data_sourceslist of str: Input data sources
named_data_sourcesdict: Named input data sources

basedir¶: The base directory. owmdir is resolved against this base

bundle¶: OWMBundle: Bundle commands

config¶

OWMConfig: Config file commands.

Without any sub-command, prints the configuration parameters

config_file¶: The config file name

context¶: Context to use instead of the default context. Commands that work with other contexts (e.g., owm contexts rm-import) will continue to use those other contexts unless otherwise indicated

contexts¶: OWMContexts: Commands for working with contexts

graph_accessor_finder¶: Finds an RDFLib graph from the given URL

namespace¶: OWMNamespace: RDF namespace commands

namespace_manager_store_name¶: The file name of the namespace database store

non_interactive¶: If this option is provided, then interactive prompts are not allowed

owmdir¶: The base directory for owmeta files. The repository provider’s files also go under here

registry¶

OWMRegistry: Commands for dealing with the class registry, a mapping of RDF types to constructs in programming languages

Although it is called the “class registry”, the registry can map RDF types to constructs other than classes in the target programming language, particularly in languages that don’t have classes (e.g., C) or where the use of classes is not preferred in that language.

repository_provider¶: The provider of the repository logic (cloning, initializing, committing, checkouts)

source¶: OWMSource: Commands for working with DataSource objects

store_name¶: The file name of the database store

temporary_directory¶: The base temporary directory for any operations that need one

property transaction_manager¶: The transaction.TransactionManager for the current connection

translator¶: OWMTranslator: Data source translator commands

type¶: OWMTypes: Commands for dealing with Python classes and RDF types

userdir¶: Root directory for user-specific configuration

class owmeta_core.command.OWMConfig(parent)[source]¶

Bases: object

Config file commands.

Without any sub-command, prints the configuration parameters

delete(key)[source]¶

Deletes a config value

Parameters

keystr: The configuration key

get(key)[source]¶

Read a config value

Parameters

keystr: The configuration key

set(key, value)[source]¶

Set a config value

Parameters

keystr: The configuration key
valuestr: The value to set

user¶: If set, configs are only for the user; otherwise, they would be committed to the repository

user_config_file¶: The user config file name

class owmeta_core.command.OWMContexts(parent)[source]¶

Bases: object

Commands for working with contexts

add_import(importer, imported)[source]¶

Add an import to the imports graph

Parameters

importerstr: The importing context
importedlist str: The imported context

bundle(context)[source]¶

Show the closest bundle that defines this context

Parameters

contextstr: The context to lookup

edit(context=None, format=None, editor=None, list_formats=False)[source]¶

Edit a provided context or the current default context.

The file name of the serialization will be passed as the sole argument to the editor. If the editor argument is not provided, will use the EDITOR environment variable. If EDITOR is also not defined, will try a few known editors until one is found. The editor must write back to the file.

Parameters

contextstr: The context to edit
formatstr: Serialization format (ex, ‘n3’, ‘nquads’). Default ‘n3’
editorstr: The program which will be used to edit the context serialization.
list_formatsbool: List the formats available for editing (I.O.W., formats that we can both read and write)

list(include_dependencies=False, include_default=False)[source]¶

List the set of contexts in the graph

Parameters

include_dependenciesbool: If set, then contexts from dependencies will be included
include_defaultbool: If set, then include the default graph in the results as well

list_changed()[source]¶: Return the set of contexts which differ from the serialization on disk

list_importers(context)[source]¶

List the contexts that import the given context

Parameters

contextstr: The context to list importers for

list_imports(context)[source]¶

List the contexts that the given context imports

Parameters

contextstr: The context to list imports for

rm(*context)[source]¶

Remove a context

Parameters

*contextstr: Context to remove

rm_import(importer, imported)[source]¶

Remove an import statement

Parameters

importerstr: The importing context
importedlist of str: An imported context

serialize(context=None, destination=None, format='nquads', include_imports=False, whole_graph=False)[source]¶

Serialize the current default context or the one provided

Parameters

contextstr: The context to save
destinationfile or str: A file-like object to write the file to or a file name. If not provided, messages the result.
formatstr: Serialization format (ex, ‘n3’, ‘nquads’)
include_importsbool: If true, then include contexts imported by the provided context in the result. The default is not to include imported contexts.
whole_graphbool: Serialize all contexts from all graphs (this probably isn’t what you want)

class owmeta_core.command.OWMNamespace(parent)[source]¶

Bases: object

RDF namespace commands

bind(prefix, uri)[source]¶

Bind a prefix to a namespace URI

Parameters

prefixstr: Prefix to bind to a namespace URI
uristr: Namespace URI to bind to a prefix

list()[source]¶: List namespace prefixes and URIs in the project

class owmeta_core.command.OWMRegistry(parent)[source]¶

Bases: object

Commands for dealing with the class registry, a mapping of RDF types to constructs in programming languages

Although it is called the “class registry”, the registry can map RDF types to constructs other than classes in the target programming language, particularly in languages that don’t have classes (e.g., C) or where the use of classes is not preferred in that language.

list(module=None, rdf_type=None, class_name=None)[source]¶

List registered classes

Parameters

modulestr: If provided, limits the registry entries returned to those that have the given module name. Optional.
rdf_typestr: If provided, limits the registry entries returned to those that have the given RDF type. Optional.
class_namestr: If provided, limits the registry entries returned to those that have the given class name. Optional.

rm(*registry_entry)[source]¶

Remove a registry entry

Parameters

*registry_entrystr: Registry entry to remove

show(*registry_entry)[source]¶

Show registry entries

Parameters

*registry_entrystr: Registry entry to show

module_access¶: OWMRegistryModuleAccess: Commands for manipulating software module access in the class registry

class owmeta_core.command.OWMRegistryModuleAccess(parent)[source]¶

Bases: object

Commands for manipulating software module access in the class registry

list(registry_entry=None)[source]¶

List module accessors

Parameters

registry_entrystr: Registry entry ID. Optional

Returns

sequence of ModuleAccessor

declare¶: OWMRegistryModuleAccessDeclare: Commands for module access declarations

show¶: OWMRegistryModuleAccessShow: Show module accessor description

class owmeta_core.command.OWMRegistryModuleAccessDeclare(parent)[source]¶

Bases: object

Commands for module access declarations

python_pip(package_name, package_version=None, index=None, module_names=None, module_id=None)[source]¶

Declare access with a Python pip package

The given module should already have been defined in the class registry. This may be achieved by the “owm save” command.

Parameters

package_namestr: Name of the package
package_versionstr: Version of the package. If not provided, will attempt to find the active version in package metadata
indexstr: The index to get the package from. Optional
module_nameslist of str: Name of the module. If not provided, will attempt to find the modules from package metadata. Multiple module names can be provided
module_idstr: URI identifier of the module. Cannot be specified along with module_name

class owmeta_core.command.OWMRegistryModuleAccessShow(parent)[source]¶

Bases: object

Show module accessor description

class owmeta_core.command.OWMSource(parent)[source]¶

Bases: object

Commands for working with DataSource objects

derivs(data_source)[source]¶

List data sources derived from the one given

Parameters

data_sourcestr: The ID of the data source to find derivatives of

list(context=None, kind=None, full=False)[source]¶

List known sources

Parameters

kindstr: Only list sources of this kind
contextstr: The context to query for sources
fullbool: Whether to (attempt to) shorten the source URIs by using the namespace manager

list_kinds(full=False)[source]¶

List kinds of DataSources available in the current context.

Note that only DataSource types which are reachable from the current context will be listed. So if, for instance, you have just saved some types (e.g., with owm save) but have not added an import of the contexts for those types, you may not see any results from this command.

Parameters

fullbool: Whether to (attempt to) shorten the source URIs by using the namespace manager

rm(*data_source)[source]¶

Remove a DataSource

Parameters

*data_sourcestr: ID of the source to remove

show(*data_source)[source]¶

Parameters

*data_sourcestr: The ID of the data source to show

class owmeta_core.command.OWMTranslator(parent)[source]¶

Bases: object

Data source translator commands

create(translator_type)[source]¶

Creates an instance of the given translator class and adds it to the graph

Parameters

translator_typestr: RDF type for the translator class

list(context=None, full=False)[source]¶

List translators

Parameters

contextstr: The root context to search
fullbool: Whether to (attempt to) shorten the source URIs by using the namespace manager

list_kinds(full=False)[source]¶

List kinds of DataTranslators

Note that only DataTranslator types which are reachable from the current context will be listed. So if, for instance, you have just saved some types (e.g., with owm save) but have not added an import of the contexts for those types, you may not see any results from this command.

Parameters

fullbool: Whether to (attempt to) shorten the translator URIs by using the namespace manager

rm(*translator)[source]¶

Remove a DataTranslator

Parameters

*translatorstr: ID of the source to remove

show(translator)[source]¶

Show a translator

Parameters

translatorstr: The translator to show

class owmeta_core.command.OWMTypes(parent)[source]¶

Bases: object

Commands for dealing with Python classes and RDF types

rm(*type)[source]¶

Removes info about the given types, like rdfs:subClassOf statements, and removes the corresponding registry entries as well

Parameters

*typestr: Types to remove

class owmeta_core.command.ProjectConnection(owm, connection, connections, *, expect_cleanup=True)[source]¶

Bases: object

Connection to the project database

transaction()[source]¶: Context manager that executes the enclosed code in a transaction and then closes the connection. Provides the connection for binding with as.

class owmeta_core.command.SaveValidationFailureRecord(user_module, stack, validation_record)[source]¶

Bases: _SaveValidationFailureRecord

Record of a validation failure in OWM.save

Create new instance of _SaveValidationFailureRecord(user_module, stack, validation_record)

class owmeta_core.command.UnimportedContextRecord(importer, context, node_index, statement)[source]¶

Bases: _UnimportedContextRecord

Stored when statements include a reference to an object but do not include the context of that object in the callback passed to OWM.save. For example, if we had a callback like this:

def owm_data(ns):
    ctxA = ns.new_context(ident='http://example.org/just-pizza-stuff')
    ctxB = ns.new_context(ident='http://example.org/stuff-sam-likes')
    sam = ctxB(Person)('sam')
    pizza = ctxA(Thing)('pizza')
    sam.likes(pizza)

it would generate this error because ctxB does not declare an import for ctxA

Create new instance of _UnimportedContextRecord(importer, context, node_index, statement)

owmeta_core.command.DEFAULT_SAVE_CALLABLE_NAME = 'owm_data'¶: Default name for the provider in the arguments to OWM.save

owmeta_core.command.DSD_DIRKEY = 'owmeta_core.command.OWMDirDataSourceDirLoader'¶: Key used for data source directory loader and file path provider