:mod:`hcpsdk.pathbuilder` --- unique object names
=================================================

.. automodule:: hcpsdk.pathbuilder
   :synopsis: Unique creation of path and object name.

Due to its internals, bulk ingest activity into HCP delivers best
possible performance if multiple parallel writes are directed to
different folders take place.

This subpackage offers functionality to create
an unique object name along with a pseudo-random path to a
folder to store the object in.

The object name generated is an UUID version 1, as defined in
`RFC 4122 <http://tools.ietf.org/pdf/rfc4122.pdf>`_\ . The algorithm uses (one of)
the servers MAC addresses, along with the system time to create
the UUID.

Intended Use
------------

Applications typically utilize a database to keep reference
pointers to objects they stored to HCP. Instead of storing a full path
as a reference to each object
(i.e.: ``https://ns.tenant.hcp.domain.com/rest/mypath/myfile``),
applications should define a *data pool* that describes the storage target
(i.e.: ``https://ns.tenant.hcp.domain.com, startpath='/rest/myapp'``).

When storing a reference, an application should store the name generated by
**hcpsdk.pathbuilder.PathBuilder.getunique()**, along with a reference
to the *data pool* used.

Benefits are:

    *   Reasonable space usage in the applications database
    *   The actual content address (the full URL) is easily computable from the
        *data pool* and **hcpsdk.pathbuilder.PathBuilder.getpath(reference)**
    *   In case the applications data needs to be migrated to a different storage
        system or a different :term:`namespace <Namespace>` within HCP, it's just a matter
        of migrating the data in the background and then changing the *data pool*
        definition, keeping application disturbence extremly low.


Classes
-------

..  _hcpsdk_pathbuilder_pathbuilder:

PathBuilder
^^^^^^^^^^^

..  autoclass:: PathBuilder
    :members:


Exceptions
----------

..  autoexception:: PathBuilderError