| Name | captura JSON |
| Version |
0.1.9
JSON |
| download |
| home_page | None |
| Summary | A framework for adding sharing and collections to existing API projects. |
| upload_time | 2024-10-15 04:32:20 |
| maintainer | None |
| docs_url | None |
| author | Adrian Cederberg |
| requires_python | <4.0,>=3.11 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
What Does This Do?
###############################################################################
The goals of captura are the following:
A. As a Base for/Enhancement of other apps:
1. Extensibility using plugins. For instance, setting a schema for the
``content`` sections of any of the 'first class' tables or adding
additional granting functionality.
2. Make it easy to add sharing between application users to existing
services. This is done using the ``content`` sections of the various
tables where users can choose how to shape their data.
B. Control of Permissions and Visibility:
1. Delegate various levels of permissions in sharing, e.g. ``view``,
``modify``, or ``own``. ``documents`` can be public or private.
2. Organize ``documents`` into ``collections`` and ``collections`` in
``collections``.
C. Emmit events for those who desire them.
Installation
###############################################################################
See the next section.
For Those Who Want to Contribute/Modify/Run
###############################################################################
First, ``git clone`` this project and go to the cloned directory. Then run
.. code:: sh
mkdir ./configs ./logs
Starting Docker
===============================================================================
A docker compose project is included so that it is easy to get a server and
database up and running. The defaults included in ``./src/app/config.py`` will
work for the compose projects mysql instance. To start the compose project do
.. code:: python
# Start the docker compose project.
docker compose --file=docker/docker-compose.yaml up --detach
docker compose --file=docker/docker-compose.yaml exec bash
and then
.. code:: bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --editable .
and then create your application configuration.
Configuration
===============================================================================
Captura is built with configurability in mind. All configuration can be written
using ``YAML`` or ``JSON``. Configuration is by default contained in the
``./configs`` directory, but the locations (paths of) of these configurations
can be set using
- ``CAPTURA_CONFIG_APP``
- ``CAPTURA_CONFIG_CLIENT``
- ``CAPTURA_LOG_CONFIG``
To see if these are set as desired, using the captura command as follows:
.. code:: bash
captura config --envvars
Captura Server
-------------------------------------------------------------------------------
There are a few important pieces of information that captura will require to
run the compose project. A minimal configuration should look something like
this:
.. code:: yaml
# ./configs/app.yaml
auth0:
use: False
issuer: auth.example.org
registration_code_salt: <big nasty string>
api:
audience: example.com
app:
client_id: <big nasty string>
client_secret: <big nasty string>
mysql: {}
app:
environment: development
host_scheme: http://
This configuration can be validated using the following command:
.. code:: bash
captura config
This will generate an error that can guide you on how to configure the app if
the configuration is malformed. Otherwise, your configuration will be printed
(with sensored secrets thanks to pydantic) to the terminal.
Once your configuration is valid then ensure that captura will run:
.. code:: bash
captura run
Client
-------------------------------------------------------------------------------
This clients configuration is inspired by ``kubectl``. This is because when
using kubernetes I found it extermely convenient to be able to switch out this
host used without directly editting configuration.
The following instructions require that captura is not run in auth0 mode. To
do so run
.. code:: bash
CAPTURA_AUTH0__USE=false captura run
this will make it such that test tokens can be generated using captura itself.
DO NOT USE PYTEST MODE IN PRODUCTION! ANYBODY CAN MAKE TOKENS IF THEY DESIRE TO!
To create your first token do:
.. code:: bash
legere tokens register \
--name "example" \
--description "example" \
--url "example.com" \
--email "example@example.com"
For subsequent tokens use ``legere tokens create``. With this token, create
a client configuration. A minimal configuration should look like
.. code:: yaml
# ./config/client.yaml
hosts:
docker_self:
host: http://localhost:8080
remote: true # Requires that ``captura run`` is invoked in the container
docker_hostless:
host: http://localhost:8080
remote: false # Client uses an app instance directly.
profiles:
docker_self:
token: *************
remote: true
use:
host: docker_self
profile: docker_self
and can be validated as follows:
.. code:: bash
legere config show
# List the hosts configured
legere config hosts --all
# List the profiles configured
legere config profiles --all
# Change the host
legere config use --host docker_hostless
To use the client on the docker host (instead of in the container, as above)
install this project and run:
.. code::
# Get the host into client.yaml
legere config docker-host --config-out configs/client.yaml
# Use this host by default
legere config use --host docker --config-out ./configs/client.yaml
# Verify
legere config show
Finally, the output format may be configured:
.. code:: yaml
...
output:
decorate: false
output: yaml
output_fallback: json
rich_theme: fruity
Dummy
-------------------------------------------------------------------------------
You probably won't need dummies. If you do, add
.. code:: yaml
dummies:
dummy:
collections:
minimum: 4
maximum: 8
documents:
minimum: 9
maximum: 16
grants:
minimum_self: 25
maximum_self: 36
minimum_other: 25
maximum_other: 36
users:
minimum: 75
maximum_uses: 100
to your application configuration and configure it to your liking. This
configuration may be validated like
.. code:: bash
simulatus preview
and controls the ``simulatus`` command, which can be used to assess the database
as a whole or per user and debug assist in debugging of tests.
Database Schema
===============================================================================
The database only requires six tables for the time being:
- **Users**. A list of user profiles. These should not contain credentials,
authentication will be outsourced to `Auth0`.
- **Collections**. These should be collections of individual documents. Some
collections will belong to a user where others will not.
- **Documents**. Should contain the documents belonging to possibly many
collections. Documents should be modifyable, and updates will be logged in
`DocumentHistories`. A document should belong to one or many users, with
the initial user being given admin permissions.
- **Grants**. Associtions between users and documents.
- **Assignments**. Associtions between collections and documents.
- **Events**. Eventually this will be used to stream events.
- **Demos**. This is to have a record of who has requested a demo. This will
eventually be a plugin and therefore this table will be optional.
Other tables may be added by plugins or other parts of the code. For instance,
the ``dummy`` module will require the ``reports`` and ``reports_grants`` table.
For Those Who Wish to use the API
###############################################################################
Captura's database model is designed to make it easy to layer on top of
existing services - essentially the goals are the following:
Getting Started
===============================================================================
Demo App
-------------------------------------------------------------------------------
First of all, request a demo at ``captura.acederberg.io/demo``. An admin will
likely accept your demo account if you are not a bot.
After your demo account is created, create your account by going to ``/login``.
This will allow you to customize your user to your liking. After this, you will
be redirected to your profile where you can obtain an authorization token.
Using this token, your client configuration should look something like:
.. code:: yaml
# ~/.captura/client.yaml
hosts:
production:
host: https://captura.acederberg.io
remote: true
profiles:
production:
token: <TOKEN FROM ABOVE STEP>
use:
host: production
profile: production
Dockerized App
-------------------------------------------------------------------------------
If you don't want to run and configure your own instance, follow the steps
above. If you really want to go this way, see ``Installation``.
Granting Process
===============================================================================
Grants can be initiated two ways: by owners inviting others and acceptance of
invitations by these others, or by non-owners requesting a level of access and
an owner accepting their request.
Owner Grants Access and Grantee Accepts.
-------------------------------------------------------------------------------
Document owner invites others. If pending grants exist, the invitations (in the
form of events) are not recreated. If the grants are deleted and pending
deletion, then adding the `force` parameter will be necessary.
.. code:: sh
client --profile granter grant documents create --uuid-user $UUID_USER $UUID_DOCUMENT
A user can read their own invitations like
.. code:: sh
client --profile grantee \
grants users read \
--pending $UUID_USER
Either of these will return an array of pending grants. A user can accept an
invitation by sending a patch with grant uuids obtained from the above
requests:
.. code:: sh
client --profile grantee grants users accept --uuid-grant $UUID_GRANT $UUID_USER
Grantee Requests and Owner Requests
-------------------------------------------------------------------------------
A user can ask for a grant to many (only public) documents like
.. code:: sh
client --profile grantee grants users --uuid-document $UUID_DOCUMENT $UUID_USER
Note that ``UUID_USER`` must be the uuid of the grantee. Only admins can request
grants for users besides their own. The document holder can then view their
pending grants:
.. code:: sh
client --profile granter grants documents read --pending $UUID_DOCUMENT
which will return the pending grants. From this a granter can obtain grant
uuids and accept it:
.. code:: sh
client --profile grantee grants documents accept $UUID_GRANT
Raw data
{
"_id": null,
"home_page": null,
"name": "captura",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Adrian Cederberg",
"author_email": "adrn.cederberg123@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/14/20/6d165e41804db144d8c0f033f6b5b8b3a770a34589f875b0d92049d12679/captura-0.1.9.tar.gz",
"platform": null,
"description": "What Does This Do?\n###############################################################################\n\nThe goals of captura are the following:\n\nA. As a Base for/Enhancement of other apps:\n\n 1. Extensibility using plugins. For instance, setting a schema for the \n ``content`` sections of any of the 'first class' tables or adding \n additional granting functionality.\n 2. Make it easy to add sharing between application users to existing \n services. This is done using the ``content`` sections of the various \n tables where users can choose how to shape their data.\n\nB. Control of Permissions and Visibility:\n\n 1. Delegate various levels of permissions in sharing, e.g. ``view``, \n ``modify``, or ``own``. ``documents`` can be public or private.\n 2. Organize ``documents`` into ``collections`` and ``collections`` in \n ``collections``.\n\nC. Emmit events for those who desire them.\n\n\nInstallation\n###############################################################################\n\nSee the next section.\n\n\nFor Those Who Want to Contribute/Modify/Run\n###############################################################################\n\nFirst, ``git clone`` this project and go to the cloned directory. Then run \n\n.. code:: sh\n\n mkdir ./configs ./logs\n\n\n\nStarting Docker\n===============================================================================\n\nA docker compose project is included so that it is easy to get a server and \ndatabase up and running. The defaults included in ``./src/app/config.py`` will \nwork for the compose projects mysql instance. To start the compose project do\n\n.. code:: python\n\n # Start the docker compose project.\n docker compose --file=docker/docker-compose.yaml up --detach\n docker compose --file=docker/docker-compose.yaml exec bash\n\n\nand then\n\n.. code:: bash\n\n python -m venv .venv\n source .venv/bin/activate \n python -m pip install --editable .\n\n\nand then create your application configuration.\n\n\nConfiguration\n===============================================================================\n\nCaptura is built with configurability in mind. All configuration can be written\nusing ``YAML`` or ``JSON``. Configuration is by default contained in the \n``./configs`` directory, but the locations (paths of) of these configurations \ncan be set using \n\n- ``CAPTURA_CONFIG_APP``\n- ``CAPTURA_CONFIG_CLIENT``\n- ``CAPTURA_LOG_CONFIG``\n\n\nTo see if these are set as desired, using the captura command as follows:\n\n.. code:: bash\n\n captura config --envvars\n\n\n\nCaptura Server\n-------------------------------------------------------------------------------\n\nThere are a few important pieces of information that captura will require to \nrun the compose project. A minimal configuration should look something like \nthis:\n\n.. code:: yaml\n\n # ./configs/app.yaml\n\n auth0: \n use: False\n issuer: auth.example.org \n registration_code_salt: <big nasty string>\n api:\n audience: example.com\n app:\n client_id: <big nasty string>\n client_secret: <big nasty string>\n mysql: {}\n app:\n environment: development\n host_scheme: http://\n\n\nThis configuration can be validated using the following command:\n\n.. code:: bash\n\n captura config\n\n\nThis will generate an error that can guide you on how to configure the app if \nthe configuration is malformed. Otherwise, your configuration will be printed\n(with sensored secrets thanks to pydantic) to the terminal. \n\nOnce your configuration is valid then ensure that captura will run:\n\n.. code:: bash\n\n captura run\n\n\nClient \n-------------------------------------------------------------------------------\n\nThis clients configuration is inspired by ``kubectl``. This is because when \nusing kubernetes I found it extermely convenient to be able to switch out this \nhost used without directly editting configuration. \n\nThe following instructions require that captura is not run in auth0 mode. To\ndo so run \n\n.. code:: bash\n\n CAPTURA_AUTH0__USE=false captura run\n\n\nthis will make it such that test tokens can be generated using captura itself. \nDO NOT USE PYTEST MODE IN PRODUCTION! ANYBODY CAN MAKE TOKENS IF THEY DESIRE TO!\nTo create your first token do:\n\n.. code:: bash\n\n legere tokens register \\\n --name \"example\" \\\n --description \"example\" \\\n --url \"example.com\" \\\n --email \"example@example.com\"\n\n\nFor subsequent tokens use ``legere tokens create``. With this token, create \na client configuration. A minimal configuration should look like\n\n.. code:: yaml\n \n # ./config/client.yaml\n hosts:\n docker_self:\n host: http://localhost:8080\n remote: true # Requires that ``captura run`` is invoked in the container\n docker_hostless:\n host: http://localhost:8080\n remote: false # Client uses an app instance directly.\n profiles: \n docker_self:\n token: *************\n remote: true\n use: \n host: docker_self\n profile: docker_self\n\n\nand can be validated as follows:\n\n.. code:: bash\n\n legere config show\n\n # List the hosts configured\n legere config hosts --all\n\n # List the profiles configured\n legere config profiles --all\n \n # Change the host\n legere config use --host docker_hostless\n\n\nTo use the client on the docker host (instead of in the container, as above)\ninstall this project and run:\n\n.. code:: \n\n # Get the host into client.yaml\n legere config docker-host --config-out configs/client.yaml\n\n # Use this host by default \n legere config use --host docker --config-out ./configs/client.yaml\n\n # Verify\n legere config show\n\n\nFinally, the output format may be configured: \n\n.. code:: yaml\n\n ...\n output:\n decorate: false\n output: yaml\n output_fallback: json\n rich_theme: fruity\n\n\n\n\nDummy\n-------------------------------------------------------------------------------\n\nYou probably won't need dummies. If you do, add \n\n.. code:: yaml\n\n dummies:\n dummy:\n collections:\n minimum: 4\n maximum: 8\n documents:\n minimum: 9\n maximum: 16\n grants:\n minimum_self: 25\n maximum_self: 36\n minimum_other: 25\n maximum_other: 36\n users:\n minimum: 75\n maximum_uses: 100\n\nto your application configuration and configure it to your liking. This\nconfiguration may be validated like\n\n.. code:: bash\n\n simulatus preview\n\n\nand controls the ``simulatus`` command, which can be used to assess the database\nas a whole or per user and debug assist in debugging of tests.\n \n\n\nDatabase Schema\n===============================================================================\n\nThe database only requires six tables for the time being:\n\n- **Users**. A list of user profiles. These should not contain credentials,\n authentication will be outsourced to `Auth0`.\n- **Collections**. These should be collections of individual documents. Some\n collections will belong to a user where others will not.\n- **Documents**. Should contain the documents belonging to possibly many\n collections. Documents should be modifyable, and updates will be logged in\n `DocumentHistories`. A document should belong to one or many users, with\n the initial user being given admin permissions.\n- **Grants**. Associtions between users and documents.\n- **Assignments**. Associtions between collections and documents.\n- **Events**. Eventually this will be used to stream events.\n- **Demos**. This is to have a record of who has requested a demo. This will \n eventually be a plugin and therefore this table will be optional.\n\nOther tables may be added by plugins or other parts of the code. For instance, \nthe ``dummy`` module will require the ``reports`` and ``reports_grants`` table.\n\nFor Those Who Wish to use the API\n###############################################################################\n\nCaptura's database model is designed to make it easy to layer on top of \nexisting services - essentially the goals are the following:\n\n\nGetting Started\n===============================================================================\n\nDemo App\n-------------------------------------------------------------------------------\n\nFirst of all, request a demo at ``captura.acederberg.io/demo``. An admin will\nlikely accept your demo account if you are not a bot. \n\nAfter your demo account is created, create your account by going to ``/login``. \nThis will allow you to customize your user to your liking. After this, you will \nbe redirected to your profile where you can obtain an authorization token.\n\nUsing this token, your client configuration should look something like:\n\n\n.. code:: yaml \n\n # ~/.captura/client.yaml\n\n hosts:\n production:\n host: https://captura.acederberg.io\n remote: true\n profiles:\n production:\n token: <TOKEN FROM ABOVE STEP>\n use:\n host: production\n profile: production\n\n\n\nDockerized App\n-------------------------------------------------------------------------------\n\nIf you don't want to run and configure your own instance, follow the steps \nabove. If you really want to go this way, see ``Installation``. \n\n\nGranting Process\n===============================================================================\n\nGrants can be initiated two ways: by owners inviting others and acceptance of\ninvitations by these others, or by non-owners requesting a level of access and\nan owner accepting their request.\n\nOwner Grants Access and Grantee Accepts.\n-------------------------------------------------------------------------------\n\nDocument owner invites others. If pending grants exist, the invitations (in the\nform of events) are not recreated. If the grants are deleted and pending\ndeletion, then adding the `force` parameter will be necessary.\n\n.. code:: sh\n\n client --profile granter grant documents create --uuid-user $UUID_USER $UUID_DOCUMENT\n\n\nA user can read their own invitations like\n\n\n.. code:: sh\n\n client --profile grantee \\\n grants users read \\\n --pending $UUID_USER\n\n\n\nEither of these will return an array of pending grants. A user can accept an\ninvitation by sending a patch with grant uuids obtained from the above\nrequests:\n\n.. code:: sh\n\n client --profile grantee grants users accept --uuid-grant $UUID_GRANT $UUID_USER\n\n\nGrantee Requests and Owner Requests\n-------------------------------------------------------------------------------\n\nA user can ask for a grant to many (only public) documents like\n\n.. code:: sh\n\n client --profile grantee grants users --uuid-document $UUID_DOCUMENT $UUID_USER\n\n\nNote that ``UUID_USER`` must be the uuid of the grantee. Only admins can request\ngrants for users besides their own. The document holder can then view their\npending grants:\n\n.. code:: sh\n\n client --profile granter grants documents read --pending $UUID_DOCUMENT\n\nwhich will return the pending grants. From this a granter can obtain grant\nuuids and accept it:\n\n.. code:: sh\n\n client --profile grantee grants documents accept $UUID_GRANT\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework for adding sharing and collections to existing API projects.",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4e7e67b09f8d69550e7963533590569bb19330b71ce5cce2cef9f2104b24ba62",
"md5": "c395c5c297af12730b44053a9c9c5053",
"sha256": "d974bd169baf1b0f7f33f00f07b35b8de05d843aa314720926d3c5fab823501b"
},
"downloads": -1,
"filename": "captura-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c395c5c297af12730b44053a9c9c5053",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 167013,
"upload_time": "2024-10-15T04:32:18",
"upload_time_iso_8601": "2024-10-15T04:32:18.780703Z",
"url": "https://files.pythonhosted.org/packages/4e/7e/67b09f8d69550e7963533590569bb19330b71ce5cce2cef9f2104b24ba62/captura-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "14206d165e41804db144d8c0f033f6b5b8b3a770a34589f875b0d92049d12679",
"md5": "9c39b95502d5968e0ff6f47e5be311cb",
"sha256": "ec054e859b439d8d8fd32dec0a457858a4329d85350149da9224c5d6902f3912"
},
"downloads": -1,
"filename": "captura-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "9c39b95502d5968e0ff6f47e5be311cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 140633,
"upload_time": "2024-10-15T04:32:20",
"upload_time_iso_8601": "2024-10-15T04:32:20.712018Z",
"url": "https://files.pythonhosted.org/packages/14/20/6d165e41804db144d8c0f033f6b5b8b3a770a34589f875b0d92049d12679/captura-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 04:32:20",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "captura"
}
