Usage

To use pycoalaip in a project:

import coalaip

Quickstart

To get started with coalaip, you should first pick a persistence layer (and an accompanying plugin) to use. For a list of available persistence layer plugins, see here.

Once you’ve configured your chosen plugin, the main workflow to follow is:

1. Create an instance of CoalaIp; 1. Generate users for yourself and other parties; 1. Register a Manifestation entity (and its accompanying Work and Copyright entities) for your IP; 1. Derive a specific Right from your IP’s Copyright (or another Right that pertains to your IP); and 1. If desired, transfer the specific Right to another party, to record a legal transaction relating to the Right (e.g. a transfer of ownership, a loan, etc).

Note

Each of CoalaIp.register_manifestation(), CoalaIp.derive_right(), and CoalaIp.transfer_right() have optional arguments to cover alternate use cases that are not explained here.

You may be interested in looking at the library reference for their complete documentation.

Warning

In the current implementation, operations that use the persistence layer are NOT ensured to succeed, and you may find that some operations need to be repeated.

A good example of this is if a storage requiring non-neglible consensus (e.g. BigchainDB) is used: the implementation assumes that everything has succeeded if it was able to write to the storage rather than confirming (later) that what it wrote was actually accepted.

Creating an instance of CoalaIp

Let’s assume you have an instance of a persistence layer plugin ready.

from coalaip import CoalaIp

plugin = Plugin(...)
coalaip = CoalaIp(plugin)

Generating users

Representations of users are defined by the persistence layer plugin. You can generate a user compatible with your chosen persistence layer by:

# Note that the plugin may dictate that you need to provide extra arguments
# to this function
user = coalaip.generate_user()

Registering a Manifestation

Upon initial registration of a Manifestation, a Work (if not provided) and Copyright are automatically generated.

manifestation_data = {...}
registration_result = coalaip.register_manifestation(manifestation_data,
                                                     copyright_holder=user)
manifestation = registration_result['manifestation']
work = registration_result['work']
copyright = registration_result['copyright']

Deriving a specific Right

You can create more specific Rights from source Rights or Copyrights if you are the current holder of the source Right.

copyright = ...
right_data = {...}
right = coalaip.derive_right(right_data, current_holder=user,
                             source_right=copyright)

Transferring a Right

Transfers of a Right will change ownership of the entity from the current holder to a new holder. A RightsAssignment entity can also be encoded in a transfer, holding more specific information about the particular details related to the transaction, such as a agreed-upon contract between the two parties, the time of the transaction, and etc.

right = ...
current_holder = ... # user representation
new_holder = ... # user representation
rights_assignment_data = {...}
rights_assignment = coalaip.transfer_right(right, rights_assignment_data,
                                           current_holder=current_holder,
                                           to=new_holder)

Querying for an Entity’s ownership history

Each entity returned has a .history() method and .current_owner property defined, in case you’re interested in finding out the ownership history of the entity.

Obtaining an instance of an Entity

If you know you have COALA IP entities persisted, but don’t have them in an Entity class (e.g. you saved the entities’ IDs in a database, and now want to use them), you can load an instance of an Entity by using the static .from_persist_id() method of that entity type.

from coalaip.entities import Manifestation

manifestation_id = '...'
manifestation = Manifestation.from_persist_id(manifestation_id,
                                              plugin=plugin)

Doing so will generate a lazy-loaded entity for you to use. Accessing the entity’s data for the first time will load the entity from the persistence layer (which may error); if you’d like to load it immediately, you can either call .load() or use the force_load flag in .from_persist_id():

manifestation = Manifestation.from_persist_id(manifestation_id,
                                              plugin=plugin)
manifestation.load()

# Or
manifestation = Manifestation.from_persist_id(manifestation_id,
                                              force_load=True,
                                              plugin=plugin)

Reference

See the library reference for a complete reference of all available classes and functions.