==============
Cornflow-tools
==============
Cornflow-core is a library that contains modules to help you create REST APIs in an easier and faster way.
It includes a set of modules that can be used to start the creation of your flask REST API and some command line
interface commands that let you create a full REST API from a JSONSchema file that represent your data or
create a JSONSchema file representing your REST API.
----------------------------------------------------
Command line interface :code:`generate_from_schema`
----------------------------------------------------
The cli :code:`generate_from_schema` allows you to automatically generate models, endpoints and schemas
from a JSONSchema. The generated files can then be added to your flask (RestFul) REST API.
How to use?
===========
To start, you need to have a json file containing the schema of the tables you want to create.
Let's assume that this file is stored on your computer as :code:`C:/Users/User/instance.json`
Open the terminal, then run:
.. code-block:: console
generate_from_schema -p C:/Users/User/instance.json -a application_name
The argument :code:`application_name` will be the prefix of the name used for the generated files, classes
and tables. It is an optional argument
This command will create a new :code:`output/` directory in the folder where is executed, containing three
directories :code:`models/`, :code:`schemas/` and :code:`endpoints/`, in which the new files will be added.
Optional arguments
==================
Output path
-----------
Use the :code:`-o` or :code:`--output-path` options to set an output path for the files. The
directories :code:`models/`, :code:`endpoint/` and :code:`schemas/` will be created directly in that
direction instead of the :code:`./output/` directory.
Example:
.. code-block:: console
generate_from_schema -p C:/Users/User/instance.json -a application_name --output-path C:/Users/User/output_files
Remove methods
--------------
By default, two endpoints are created:
- A global endpoint, with three methods:
- :code:`get()`, that returns all the element of the table.
- :code:`post(**kwargs)`, that adds a new row to the table.
- A detail endpoint, with three methods:
- :code:`get(idx)`, that returns the entry with the given id.
- :code:`put(idx, **kwargs)`, that updates the entry with the given id with the given data.
- :code:`patch(idx, **kwargs)` that patches the entry with the given id with the given oatch.
- :code:`delete(idx)`, that deletes the entry with the given id.
If one or several of those methods are not necessary, the option :code:`--remove-methods` or :code:`-r` allows to not
generate some of those methods.
Example:
.. code-block:: console
generate_from_schema -p C:/Users/User/instance.json -a application_name --remove-methods get-list -r delete-detail
In that example, for each table, the detail endpoint will not contain the :code:`delete()` method and
the list endpoint will not contain the :code:`get()` method. The choices for this method are
:code:`get-list`, :code:`post-list`, :code:`get-detail`, :code:`put-detail`, :code:`delete-detail` and :code:`patch-detail`.
One table
---------
By default, the module accepts schemas that contain several tables at once (see for example the
instance schema for the rostering application, in **cornflow-dags**). If you only need to create one table,
the schema can also have the following format:
.. code-block::
{
"type": "array",
"description": "Table with the employee master information",
"items": {
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for each employee.",
"type": "integer",
},
"name": {
"description": "The name of each employee.",
"type": "string",
},
},
"required": [
"id",
"name",
]
}
}
that is, the schema is simply the description of the table. In that case, you can use
the :code:`--one` option to indicate the name of the table. If not, the generated table will be called
:code:`{application_name}_data` by default.
Example:
.. code-block:: console
generate_from_schema -p C:/Users/User/instance.json -a application_name --one table_name
In that case, only one table will be created.
Notes
=====
Primary keys
------------
If your table contains a field named :code:`id`, this field will automatically be considered the
primary key of the table. If it doesn't, an autoincrementing column :code:`id` will be added to the
table and :code:`id` will be set as the primary key of the table.
Foreign keys
------------
If a field is a foreign key to another table, this can be indicated in the schema.
You only need to add the property :code:`foreign_key` in the information about the property.
Its value must have the format :code:`table_name.key`, :code:`table_name` being the name of the table
the attributes refers to, and :code:`key` being the name of the foreign key in the original table.
For example, if the table employee has a :code:`id_job` property that is a foreign_key referring to
the property :code:`id` of the table :code:`jobs`, then the property :code:`id_job` can be described
as follows:
.. code-block::
{
...,
"id_job": {
"type": "integer",
"description": "The id. of the job",
"foreign_key": "jobs.id"
},
...
}
If the property :code:`foreign_key` is left empty, it is assumed that the key is not a foreign key.
-----------------------------------
Module :code:`schema_from_models`
-----------------------------------
The cli :code:`schema_from_models` allows you to automatically generate a JSONSchema based on
a set of models.
How to use?
===========
To start, you need to have a directory containing the SQLAlchemy models.
Let's assume that this directory is stored on your computer as :code:`C:/Users/User/models`
Open the terminal and run:
.. code-block:: console
schema_from_models -p C:/Users/User/models
This command will create a new :code:`output_schema.json` directory in the directory from where it was executed,
containing the generated schema.
Optional arguments
==================
Output path
-----------
Specify an output path using the argument :code:`-o` or :code:`--output_path`.
Ignore files
------------
By default, all the python files that do not contain models will be ignored. However, if you
need to specify that some model files need to be ignored, you can use the :code:`-i` or
:code:`--ignore-files` option. This option takes as arguments the name of the files to ignore
with their extension. Example:
.. code-block:: console
schema_from_models -p C:/Users/User/models --ignore-files instance.py -i execution.py
Raw data
{
"_id": null,
"home_page": "https://github.com/baobabsoluciones/cornflow",
"name": "cornflow-core",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "baobab soluciones",
"author_email": "sistemas@baobabsoluciones.es",
"download_url": "https://files.pythonhosted.org/packages/8f/8d/8ea43719ed694aab65f3dd5655f1e46c2938f7a10d36875cfd2612a99907/cornflow-core-0.1.5.tar.gz",
"platform": null,
"description": "==============\nCornflow-tools\n==============\n\nCornflow-core is a library that contains modules to help you create REST APIs in an easier and faster way.\nIt includes a set of modules that can be used to start the creation of your flask REST API and some command line\ninterface commands that let you create a full REST API from a JSONSchema file that represent your data or\ncreate a JSONSchema file representing your REST API.\n\n----------------------------------------------------\nCommand line interface :code:`generate_from_schema`\n----------------------------------------------------\nThe cli :code:`generate_from_schema` allows you to automatically generate models, endpoints and schemas\nfrom a JSONSchema. The generated files can then be added to your flask (RestFul) REST API.\n\nHow to use?\n===========\n\nTo start, you need to have a json file containing the schema of the tables you want to create.\nLet's assume that this file is stored on your computer as :code:`C:/Users/User/instance.json`\nOpen the terminal, then run:\n\n.. code-block:: console\n\n generate_from_schema -p C:/Users/User/instance.json -a application_name\n\nThe argument :code:`application_name` will be the prefix of the name used for the generated files, classes\nand tables. It is an optional argument\nThis command will create a new :code:`output/` directory in the folder where is executed, containing three\ndirectories :code:`models/`, :code:`schemas/` and :code:`endpoints/`, in which the new files will be added.\n\nOptional arguments\n==================\n\nOutput path\n-----------\n\nUse the :code:`-o` or :code:`--output-path` options to set an output path for the files. The\ndirectories :code:`models/`, :code:`endpoint/` and :code:`schemas/` will be created directly in that\ndirection instead of the :code:`./output/` directory.\n\nExample:\n\n.. code-block:: console\n\n generate_from_schema -p C:/Users/User/instance.json -a application_name --output-path C:/Users/User/output_files\n\n\nRemove methods\n--------------\n\nBy default, two endpoints are created:\n\n- A global endpoint, with three methods:\n - :code:`get()`, that returns all the element of the table.\n - :code:`post(**kwargs)`, that adds a new row to the table.\n- A detail endpoint, with three methods:\n - :code:`get(idx)`, that returns the entry with the given id.\n - :code:`put(idx, **kwargs)`, that updates the entry with the given id with the given data.\n - :code:`patch(idx, **kwargs)` that patches the entry with the given id with the given oatch.\n - :code:`delete(idx)`, that deletes the entry with the given id.\n\nIf one or several of those methods are not necessary, the option :code:`--remove-methods` or :code:`-r` allows to not\ngenerate some of those methods. \n\nExample:\n\n.. code-block:: console\n\n generate_from_schema -p C:/Users/User/instance.json -a application_name --remove-methods get-list -r delete-detail\n\nIn that example, for each table, the detail endpoint will not contain the :code:`delete()` method and\nthe list endpoint will not contain the :code:`get()` method. The choices for this method are\n:code:`get-list`, :code:`post-list`, :code:`get-detail`, :code:`put-detail`, :code:`delete-detail` and :code:`patch-detail`.\n\nOne table\n---------\n\nBy default, the module accepts schemas that contain several tables at once (see for example the\ninstance schema for the rostering application, in **cornflow-dags**). If you only need to create one table,\nthe schema can also have the following format:\n\n.. code-block::\n\n {\n \"type\": \"array\",\n \"description\": \"Table with the employee master information\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"id\": {\n \"description\": \"The unique identifier for each employee.\",\n \"type\": \"integer\",\n },\n \"name\": {\n \"description\": \"The name of each employee.\",\n \"type\": \"string\",\n },\n },\n \"required\": [\n \"id\",\n \"name\",\n ]\n }\n }\n\nthat is, the schema is simply the description of the table. In that case, you can use\nthe :code:`--one` option to indicate the name of the table. If not, the generated table will be called\n:code:`{application_name}_data` by default.\n\nExample:\n\n.. code-block:: console\n\n generate_from_schema -p C:/Users/User/instance.json -a application_name --one table_name\n\nIn that case, only one table will be created.\n\nNotes\n=====\nPrimary keys\n------------\n\nIf your table contains a field named :code:`id`, this field will automatically be considered the\nprimary key of the table. If it doesn't, an autoincrementing column :code:`id` will be added to the\ntable and :code:`id` will be set as the primary key of the table.\n\nForeign keys\n------------\nIf a field is a foreign key to another table, this can be indicated in the schema.\nYou only need to add the property :code:`foreign_key` in the information about the property.\nIts value must have the format :code:`table_name.key`, :code:`table_name` being the name of the table\nthe attributes refers to, and :code:`key` being the name of the foreign key in the original table.\nFor example, if the table employee has a :code:`id_job` property that is a foreign_key referring to\nthe property :code:`id` of the table :code:`jobs`, then the property :code:`id_job` can be described\nas follows:\n\n.. code-block::\n\n {\n ...,\n \"id_job\": {\n \"type\": \"integer\",\n \"description\": \"The id. of the job\",\n \"foreign_key\": \"jobs.id\"\n },\n ...\n }\n\nIf the property :code:`foreign_key` is left empty, it is assumed that the key is not a foreign key.\n\n-----------------------------------\nModule :code:`schema_from_models`\n-----------------------------------\nThe cli :code:`schema_from_models` allows you to automatically generate a JSONSchema based on\na set of models.\n\nHow to use?\n===========\n\nTo start, you need to have a directory containing the SQLAlchemy models.\nLet's assume that this directory is stored on your computer as :code:`C:/Users/User/models`\nOpen the terminal and run:\n\n.. code-block:: console\n\n schema_from_models -p C:/Users/User/models\n\nThis command will create a new :code:`output_schema.json` directory in the directory from where it was executed,\ncontaining the generated schema.\n\n\nOptional arguments\n==================\n\nOutput path\n-----------\n\nSpecify an output path using the argument :code:`-o` or :code:`--output_path`.\n\nIgnore files\n------------\n\nBy default, all the python files that do not contain models will be ignored. However, if you\nneed to specify that some model files need to be ignored, you can use the :code:`-i` or\n:code:`--ignore-files` option. This option takes as arguments the name of the files to ignore\nwith their extension. Example:\n\n.. code-block:: console\n\n schema_from_models -p C:/Users/User/models --ignore-files instance.py -i execution.py\n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "REST API flask backend components used by cornflow and other REST APIs",
"version": "0.1.5",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c4d8565c4faac32da8fa3057c1c7edeb08dd9d7e22f1cc40c6cfa6031f6d7bc",
"md5": "8f68700059195dc634c4fbd01282be8d",
"sha256": "d5fcc53e9dd5697a7b8e7d0add569b1f101f73314fdc4ac8613f0ee4bd9e47c4"
},
"downloads": -1,
"filename": "cornflow_core-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f68700059195dc634c4fbd01282be8d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 57878,
"upload_time": "2023-02-09T19:08:34",
"upload_time_iso_8601": "2023-02-09T19:08:34.820958Z",
"url": "https://files.pythonhosted.org/packages/9c/4d/8565c4faac32da8fa3057c1c7edeb08dd9d7e22f1cc40c6cfa6031f6d7bc/cornflow_core-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8f8d8ea43719ed694aab65f3dd5655f1e46c2938f7a10d36875cfd2612a99907",
"md5": "7907662dd331c72ba6c9772620ba8955",
"sha256": "60075ec5a70116e8327694231adf59c07818d0abdf5db509ee88d06f44e96a0f"
},
"downloads": -1,
"filename": "cornflow-core-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "7907662dd331c72ba6c9772620ba8955",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 41472,
"upload_time": "2023-02-09T19:08:36",
"upload_time_iso_8601": "2023-02-09T19:08:36.583147Z",
"url": "https://files.pythonhosted.org/packages/8f/8d/8ea43719ed694aab65f3dd5655f1e46c2938f7a10d36875cfd2612a99907/cornflow-core-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-09 19:08:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "baobabsoluciones",
"github_project": "cornflow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cornflow-core"
}
JSON
