Modules

API and separation of responsibility

responsibility
(means reason to change code if functionality changes) should lay at one single point of code (packages/modules in this case), see also Refactoring & Clean Code.
layer
loosly group of modules that follow these rules: * must not import from upper layer * should not import from same layer * may import interfaces from all layers * may import from lower layer

Application Layer

adhocracy_core Configure, add dependency packages/modules, start application.

Frontend Views, Client Communication Layer

adhocracy_core.rest Configure rest api packages.
adhocracy_core.rest.views GET/POST/PUT requests processing.
adhocracy_core.rest.batchview POST batch requests processing.
adhocracy_core.rest.schemas Data structures / validation specific to rest api requests.
adhocracy_core.rest.subscriber Subscriber to modify the http response object.
adhocracy_core.rest.exceptions HTTP Exception (500, 310, 404,..) processing.
adhocracy_core.caching Adapter and helper functions to set the http response caching headers.
adhocracy_core.authentication Authentication with support for token http headers.
adhocracy_core.websockets Asynchronous client-server communication via Websockets.

Registry, Factories, Access to Metadata Layer

adhocracy_core.content Create resources, get sheets/metadata, permission checks.
adhocracy_core.changelog Transaction changelog for resources.

Resource Handling Layer

adhocracy_core.resources Resource types mapped to sheets (OpenClosePrinciple), object hierarchy.
adhocracy_core.resources.base Resource base implementation with zodb persistence.
adhocracy_core.resources.simple Basic simple type without children and non versionable.
adhocracy_core.resources.pool Basic type with children typically to create process structures.
adhocracy_core.resources.item Basic Pool for specific Itemversions typically to create process content.
adhocracy_core.resources.itemversion Basic versionable type typically for process content.
adhocracy_core.resources.root Root type to create initial object hierarchy and set global Permissions.
adhocracy_core.resources.principal Principal types (user/group) and helpers to search/get user information.
adhocracy_core.resources.subscriber Autoupdate resources.
adhocracy_core.sheets Data structures/validation, set/get for an isolated set of resource data.
adhocracy_core.catalog Configure search catalogs.
adhocracy_core.catalog.adhocracy Adhocracy catalog and index views.
adhocracy_core.catalog.subscriber Reindex subscribers.
adhocracy_core.authorization Authorization with roles/local roles mapped to adhocracy principals.
adhocracy_core.messaging Send messages to Principals.
adhocracy_core.graph Set/Get Resource References / versions graph (DAG) helpers.
adhocracy_core.workflows Finite state machines for resources.

Interfaces, Utils Layer

adhocracy_core.interfaces Interfaces for plugable dependencies, basic metadata structures.
adhocracy_core.utils Helper functions shared between modules.
adhocracy_core.events Hooks to modify runtime behavior (use ‘subscriber.py’ in you package).
adhocracy_core.schema Basic data structures and validation.
adhocracy_core.exceptions Internal Exceptions.

Other stuff

adhocracy_core.scaffolds Create scaffolds to customize or extend adhocracy.
adhocracy_core.scripts scripts.
adhocracy_core.stats Send runtime statistics to statsd <http://statsd.readthedocs.org>.
adhocracy_core.auditing Log which user modifies resources in additional ‘audit’ database.
adhocracy_core.evolution Scripts to migrate legacy objects in existing databases.
adhocracy_core.registry
adhocracy_core.renderers Additional pyramid renderers.
adhocracy_core.templates

TODO: move all scripts to adhocracy_core.scripts

Substanced dependencies

Extend/Customize

  • must follow Rules for extensible pyramid apps: configuration, configuration extentensions, view/asset overriding, event subscribers. Use imperative-configuration, except for views configuration-declaration.
  • may use the underlaying zope component architecture provided by the application registry directly. may not use the global zope component registry, see also ZCA in pyramid.
  • must follow rules for module layer (see above)
  • make code dependencies pluggable to allow different implementations (other authentication, references storage, data storage, search, ..) Dependencies should have an interface to describe public methods.
  • override resource/sheet metadata, see adhocracy_sample

Note

You can use the script bin/ad_check_forbidden_imports to list suspicious imports

Naming conventions

  • Non-versionable resources types are named resource.x.IX with a sheet named sheet.x.IX.
  • Versionable resources types are named resource.x.IXVersion (inherits from IITemVersion) with a sheet named sheet.x.IX. They belong to the container (parent) resource type called resource.x.IX (inherits from IItem).
  • Resource/sheet types to express RDF like statements are named after the verb, for example: IRate.