Metadata-Version: 2.1
Name: notelist
Version: 0.9.0
Summary: Tag based note taking REST API
Home-page: https://github.com/jajimenez/notelist
Author: Jose A. Jimenez
Author-email: jajimenezcarm@gmail.com
License: MIT
Description: # Notelist
        Notelist is a tag based note taking REST API written in Python and based on the
        Flask framework.
        
        Main features:
        
        - Users, notebooks and notes management
        - JWT based authentication
        - MongoDB, DynamoDB or a local JSON file for the data storage
        
        #### Project information:
        - Version: 0.9.0
        - Author: Jose A. Jimenez (jajimenezcarm@gmail.com)
        - License: MIT License
        - Repository: https://github.com/jajimenez/notelist
        
        ## How to install
        
        You can download and install Notelist CLI from the **PyPI** repository with
        **PIP**:
        
        ```bash
        pip install notelist
        ```
        
        ## How to build
        
        To generate the **built package** and the **source archive**, run the following
        commands (the *wheel* Python package is required for generating the built
        package):
        
        ```bash
        python setup.py bdist_wheel sdist
        ```
        
        ## How to run
        
        To run Notelist, you can set the following **environment variables**:
        
        **Main variables:**
        
        - `FLASK_APP`:<br>
        Its value must be the Notelist package name (`notelist`) if you are running the
        API through the Python package once its installed or the path to the API source
        code directory (`src/notelist`) if you are running the API through the project
        directory.
        
        - `NL_SECRET_KEY`:<br>
        The Secret Key is used for storing session information specific to a user from
        one request to the next. Its value must be a **random** sequence of characters
        and must be kept **secret**.
        
        - `NL_DB_SYS`:<br>
        Database system (`mongodb`, `dynamodb` or `localst`). `localst` (local JSON
        file) should be used only for testing purposes.
        
        - `NL_ALLOW_ORIG` (optional):<br>
        Value of the **Access-Control-Allow-Origin** response header. The value of this
        header determines which host is allow to make requests to the API from a
        front-end application (from JavaScript code).<br><br>
        If this API is used through a front-end application and the API and the
        front-end application are in the same host, then it's not needed to set this
        header. If the API and the front-end are in different hosts, then the header
        must be set to the host of the front-end application (starting with
        "https://").<br><br>
        The value `*` for the header allows a front-end from any host to make requests
        to the API but this is not recommended and is not supported by all browsers.
        
        - `NL_ROOT_DOC` (optional):<br>
        If its value is `1`, the root route (`/`) returns a documentation page. If its
        value is `0` (default), the root route returns a 404 error response.
        
        **MongoDB variables (only if `NL_DB_SYS` is `mongodb`):**
        
        - `NL_MONGODB_URI`:<br>
        MongoDB URI (e.g. `mongodb://username:password@localhost:27017`).
        
        - `NL_MONGODB_DB`:<br>
        MongoDB database name (e.g. `notelist`).
        
        - `NL_MONGODB_US_COL`<br>
        MongoDB users collection name (e.g. `users`).
        
        - `NL_MONGODB_NB_COL`<br>
        MongoDB notebooks collection name (e.g. `notebooks`).
        
        - `NL_MONGODB_NO_COL`<br>
        MongoDB notes collection name (e.g. `notes`).
        
        - `NL_MONGODB_BL_COL`<br>
        MongoDB block list collection name (e.g. `blocklist`). This collection stores
        temporary data about revoked access tokens.
        
        **DynamoDB variables (only if `NL_DB_SYS` is `dynamodb`):**
        
        - `NL_DYNAMODB_AWS_ENDPOINT` (optional):<br>
        AWS endpoint URL (e.g. `http://localhost:8000`).
        
        - `NL_DYNAMODB_AWS_REGION` (optional):<br>
        AWS region name (e.g. `eu-west-1`).
        
        - `NL_DYNAMODB_AWS_ACCESS_KEY_ID` (optional):<br>
        AWS Access Key ID.
        
        - `NL_DYNAMODB_AWS_SECRET_ACCESS_KEY` (optional):<br>
        AWS Secret Access Key.
        
        - `NL_DYNAMODB_AWS_SESSION_TOKEN` (optional):<br>
        AWS Session Token.
        
        - `NL_DYNAMODB_US_TAB`<br>
        DynamoDB users table name (e.g. `users`).
        
        - `NL_DYNAMODB_NB_TAB`<br>
        DynamoDB notebooks table name (e.g. `notebooks`).
        
        - `NL_DYNAMODB_NO_TAB`<br>
        DynamoDB notes table name (e.g. `notes`).
        
        - `NL_DYNAMODB_BL_TAB`<br>
        DynamoDB block list table name (e.g. `blocklist`). This table stores
        temporary data about revoked access tokens.
        
        **Local Storage variables (only if `NL_DB_SYS` is `localst`):**
        
        - `NL_LOCALST_PATH`:<br>
        JSON file path (e.g. `notelist.json`).
        
        Once the environment variables are set, we have to create the **database** and
        the **collections/tables** (if they don't already exist) before running the
        API. You can do this running the following command:
        
        ```bash
        flask db create
        ```
        
        Run `flask db --help` to see the database commands help information.
        
        If are using **MongoDB** as the database system, the command above creates the
        MongoDB **database**, the **collections** (including their **indexes**).
        
        If you are using **DynamoDB** as the database system, the command above creates
        the DynamoDB **tables** (including their **indexes**). The tables are created
        with the **On Demand** billing mode. Please modify the tables or the API source
        code according to your needs if you want to use the **Provisioned** billing
        mode. The command doesn't set a **TTL** (Time to Live) field, but it's
        recommended that in the **Block List** table you enable the TTL DynamoDB
        feature for the `expiration` field (which is a 10 digit timestamp in seconds),
        so that each item/document is deleted after that amount of time. The Block List
        table stores temporary data about revoked authentication tokens.
        
        Then you can **create a user** by running the following command:
        
        ```bash
        flask user create --username <string> --admin <boolean> --enabled <boolean> --name <string> --email <string> [--password <string>]
        ```
        
        If you omit the `--password` option, the password will be prompted and hidden.
        
        - Example for an administrator user:<br>
          `flask user create --username example1 --admin y --enabled y`
        
        - Example for a regular user:<br>
          `flask user create --username example2 --enabled y`
        
        Run `flask user --help` to see the user commands help information.
        
        To run Notelist on a **local development** server (**not** for a production
        environment) from the Python package installed, run one of the following
        commands:
        
        ```bash
        flask run
        python -m notelist
        ```
        
        Alternatively, you can run the second command above from the source code
        directory (`src/notelist`) :
        
        ```bash
        cd src
        python -m notelist
        ```
        
        To run Notelist in a **production** environment, you should do it through a
        **WSGI** server (e.g. Gunicorn). You can install **Gunicorn** through the
        `requirements_pro.txt` file:
        
        ```bash
        pip install -r requirements_pro.txt
        ```
        
        Once you have both Notelist and Gunicorn installed, you can run Notelist
        through Gunicorn running the following command (in this example we set 1 worker
        process listening to connections from outside our computer on port 5000):
        
        ```bash
        gunicorn -b 0.0.0.0:5000 notelist:app
        ```
        
        ## How to run with Docker
        
        You can run a Docker container with Notelist. For example, the following
        command downloads the Docker image from the Docker Hub repository and runs a
        container from the image using a single JSON file stored in the container:
        
        ```bash
        docker container run --name notelist -d -p 5000:5000 \
        -e NL_SECRET_KEY=long_random_string \
        -e NL_ROOT_DOC=1 \
        -e NL_DB_SYS=localst \
        -e NL_LOCALST_PATH=/home/notelist.json \
        jajim/notelist:0.9.0
        ```
        
        Where `NL_SECRET_KEY` must be a long random sequence of characters and must be
        kept secret.
        
        Using a single JSON file for the data storage should be only for testing
        purposes. For production use, you should run a container which uses MongoDB or
        DynamoDB.
        
        Once the container is running, we have to create the database and a user. For
        example:
        
        ```bash
        docker container exec -it notelist flask db create
        docker container exec -it notelist flask user create --username admin --admin y --enabled y
        ```
        
        ## How to run with Docker Compose
        
        The easiest way to try Notelist is by using **Docker Compose** to run a
        container for the API and another container for the MongoDB server for the data storage. To create and run the containers, run the following command from the
        same directory of the `docker-compose.yml` file (the project directory):
        
        ```bash
        docker compose up -d
        ```
        
        Check the `docker-compose.yml` file to see how the containers are created.
        
        ## How to run the unit tests
        
        To run all the unit tests, run the following command from the project
        directory:
        
        ```bash
        python -m unittest discover test
        ```
        
        Read the `test/env.py` file for information about how to run MongoDB and
        DynamoDB integration tests.
        
        ## Documentation
        
        You can find the documentation of all the operations of the API by running the
        API with the  `NL_ROOT_DOC` environment variable set to `1` and navigating to
        the root route (`/`) in a browser.
        
        ## Request examples
        
        The following are some examples of requests to the Notelist API with the `curl`
        command assuming that the API is running on our local computer and listening on
        port 5000.
        
        Log in:
        
        ```bash
        curl -X 'POST' 'http://localhost:5000/auth/login' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -d '{"username": "<username>", "password": "<password>"}'
        ```
        
        Create a notebook:
        
        ```bash
        curl -X 'POST' 'http://localhost:5000/notebooks/notebook' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer <access_token>' \
        -d '{"name": "Example Notebook"}'
        ```
        
        Create a note:
        
        ```bash
        curl -X 'POST' 'http://localhost:5000/notes/note' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer <access_token>' \
        -d '{"notebook_id": "<notebook_id>", "archived": false, "title": "Example Note", "body": "This is a test note", tags: ["tag_name_1", "tag_name_2"]}'
        ```
        
        Get the notes of a notebook by a filter:
        
        ```bash
        curl -X 'POST' 'http://localhost:5000/notes/notes/<notebook_id>' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer <access_token>' \
        -d '{"archived": false, "tags": ["tag_name_1", "tag_name_2"]}'
        ```
        
        Search for notebooks and notes that match a given text:
        
        ```bash
        curl -X 'GET' 'http://localhost:5000/search/<search>' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer <access_token>'
        ```
        
        Log out:
        
        ```bash
        curl -X 'GET' 'http://localhost:5000/auth/logout' \
        -H 'Accept: application/json' \
        -H 'Content-Type: application/json' \
        -H 'Authorization: Bearer <access_token>'
        ```
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9.0
Description-Content-Type: text/markdown
