# RapidPro Flow Toolkit
Toolkit for using spreadsheets to create and modify RapidPro flows.
# Quickstart
```sh
pip install rpft
rpft --help
```
# Command Line Interface (CLI)
The CLI allows spreadsheets in various formats to be converted to RapidPro flows in JSON format. Full details of the available options can be found via the help feature:
```sh
rpft --help
```
Below is a concrete example of a valid execution of the command line tool. The line breaks are merely for improving readability; the command would also be valid on a single line.
```sh
rpft create_flows \
--output flows.json \
--datamodels=tests.input.example1.nestedmodel \
--format=csv \
src/rpft/tests/input/example1/content_index.csv
```
# Using the toolkit in other Python projects
1. Add the package `rpft` as a dependency of your project e.g. in requirements.txt or pyproject.toml
1. Import the `create_flows` function
1. Call `create_flows` to convert spreadsheets to flows
```python
from rpft.converters import create_flows
sheets = ["sheet1.csv", "sheet2.csv"]
create_flows(
sheets, "flows.json", "csv", data_models="your_project.models"
)
```
_It should be noted that this project is still considered beta software that may change significantly at any time._
# RapidPro flow spreadsheet format
The expected contents of the input spreadsheets is [documented separately][3].
# Processing Google Sheets
It is possible to read in spreadsheets via the Google Sheets API by specifying `--format=google_sheets` on the command line. Spreadsheets must be in the Google Sheets format rather than XLSX, CSV, etc.
Instead of specifying paths to individual spreadsheets on your local filesystem, you must supply the IDs of the Sheets you want to process. The ID can be extracted from the URL of the Sheet i.e. docs.google.com/spreadsheets/d/**ID**/edit.
The toolkit will need to authenticate with the Google Sheets API and be authorized to access your spreadsheets. Two methods for doing this are supported.
- **OAuth 2.0 for installed applications**: for cases where human interaction is possible e.g. when using the CLI
- **Service accounts**: for cases where interaction is not possible or desired e.g. in automated pipelines
## Installed applications
Follow the steps in the [setup your environment section][1] of the Google Sheets quickstart for Python.
Once you have a `credentials.json` file in your current working directory, the toolkit will automatically use it to authenticate whenever you use the toolkit. The refresh token (`token.json`) will be saved automatically in the current working directory so that it is not necessary to go through the full authentication process every time.
## Service accounts
Follow the steps in the [creating a service account section][2] to obtain a service account key. The toolkit will accept the key as an environment variable called `CREDENTIALS`.
```sh
export CREDENTIALS=$(cat service-account-key.json)
rpft ...
```
# Development
For instructions on how to set up your development environment for developing the toolkit, see the [development][4] page.
[1]: https://developers.google.com/sheets/api/quickstart/python#set_up_your_environment
[2]: https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount
[3]: https://docs.google.com/document/d/1Onx2RhNoWKW9BQvFrgTc5R5hcwDy1OMsLKnNB7YxQH0/edit?pli=1#
[4]: https://github.com/IDEMSInternational/rapidpro-flow-toolkit/docs/development.md
Raw data
{
"_id": null,
"home_page": "",
"name": "rpft",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "rapidpro,flow,tools,toolkit",
"author": "",
"author_email": "IDEMS International <communications@idems.international>",
"download_url": "https://files.pythonhosted.org/packages/cf/c1/1cdbbe34298fa05db8ad6280c2b423d2255d8df33854de9478aadb8fdf2d/rpft-1.0.0.tar.gz",
"platform": null,
"description": "# RapidPro Flow Toolkit\n\nToolkit for using spreadsheets to create and modify RapidPro flows.\n\n# Quickstart\n\n```sh\npip install rpft\nrpft --help\n```\n\n# Command Line Interface (CLI)\n\nThe CLI allows spreadsheets in various formats to be converted to RapidPro flows in JSON format. Full details of the available options can be found via the help feature:\n\n```sh\nrpft --help\n```\n\nBelow is a concrete example of a valid execution of the command line tool. The line breaks are merely for improving readability; the command would also be valid on a single line.\n\n```sh\nrpft create_flows \\\n --output flows.json \\\n --datamodels=tests.input.example1.nestedmodel \\\n --format=csv \\\n src/rpft/tests/input/example1/content_index.csv\n```\n\n# Using the toolkit in other Python projects\n\n1. Add the package `rpft` as a dependency of your project e.g. in requirements.txt or pyproject.toml\n1. Import the `create_flows` function\n1. Call `create_flows` to convert spreadsheets to flows\n\n```python\nfrom rpft.converters import create_flows\n\nsheets = [\"sheet1.csv\", \"sheet2.csv\"]\ncreate_flows(\n sheets, \"flows.json\", \"csv\", data_models=\"your_project.models\"\n)\n```\n\n_It should be noted that this project is still considered beta software that may change significantly at any time._\n\n# RapidPro flow spreadsheet format\n\nThe expected contents of the input spreadsheets is [documented separately][3].\n\n# Processing Google Sheets\n\nIt is possible to read in spreadsheets via the Google Sheets API by specifying `--format=google_sheets` on the command line. Spreadsheets must be in the Google Sheets format rather than XLSX, CSV, etc.\n\nInstead of specifying paths to individual spreadsheets on your local filesystem, you must supply the IDs of the Sheets you want to process. The ID can be extracted from the URL of the Sheet i.e. docs.google.com/spreadsheets/d/**ID**/edit.\n\nThe toolkit will need to authenticate with the Google Sheets API and be authorized to access your spreadsheets. Two methods for doing this are supported.\n\n- **OAuth 2.0 for installed applications**: for cases where human interaction is possible e.g. when using the CLI\n- **Service accounts**: for cases where interaction is not possible or desired e.g. in automated pipelines\n\n## Installed applications\n\nFollow the steps in the [setup your environment section][1] of the Google Sheets quickstart for Python.\n\nOnce you have a `credentials.json` file in your current working directory, the toolkit will automatically use it to authenticate whenever you use the toolkit. The refresh token (`token.json`) will be saved automatically in the current working directory so that it is not necessary to go through the full authentication process every time.\n\n## Service accounts\n\nFollow the steps in the [creating a service account section][2] to obtain a service account key. The toolkit will accept the key as an environment variable called `CREDENTIALS`.\n\n```sh\nexport CREDENTIALS=$(cat service-account-key.json)\nrpft ...\n```\n\n# Development\n\nFor instructions on how to set up your development environment for developing the toolkit, see the [development][4] page.\n\n[1]: https://developers.google.com/sheets/api/quickstart/python#set_up_your_environment\n[2]: https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount\n[3]: https://docs.google.com/document/d/1Onx2RhNoWKW9BQvFrgTc5R5hcwDy1OMsLKnNB7YxQH0/edit?pli=1#\n[4]: https://github.com/IDEMSInternational/rapidpro-flow-toolkit/docs/development.md\n",
"bugtrack_url": null,
"license": "LGPL-2.1-or-later",
"summary": "Toolkit for using spreadsheets to create and modify RapidPro flows",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/IDEMSInternational/rapidpro-flow-toolkit",
"Repository": "https://github.com/IDEMSInternational/rapidpro-flow-toolkit"
},
"split_keywords": [
"rapidpro",
"flow",
"tools",
"toolkit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d6f8e87d2e70ac157520e4eb533efe3df90a5a59b549c4664ab09e14086eee3",
"md5": "b028bfd4991853aa0051b5096701e543",
"sha256": "0468325c5c77baa08f2f971bbf8796b0815335e504985e23589db2ce744663c3"
},
"downloads": -1,
"filename": "rpft-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b028bfd4991853aa0051b5096701e543",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 95647,
"upload_time": "2023-07-12T14:12:24",
"upload_time_iso_8601": "2023-07-12T14:12:24.610645Z",
"url": "https://files.pythonhosted.org/packages/1d/6f/8e87d2e70ac157520e4eb533efe3df90a5a59b549c4664ab09e14086eee3/rpft-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cfc11cdbbe34298fa05db8ad6280c2b423d2255d8df33854de9478aadb8fdf2d",
"md5": "dcdbdb66d5efa7249edb257fc18d4811",
"sha256": "a1f2c38fa26d3a67c8dfdca84f75c48ada0e64d3434278ee71d0500cb07c87b9"
},
"downloads": -1,
"filename": "rpft-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "dcdbdb66d5efa7249edb257fc18d4811",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 76791,
"upload_time": "2023-07-12T14:12:26",
"upload_time_iso_8601": "2023-07-12T14:12:26.343932Z",
"url": "https://files.pythonhosted.org/packages/cf/c1/1cdbbe34298fa05db8ad6280c2b423d2255d8df33854de9478aadb8fdf2d/rpft-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-12 14:12:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IDEMSInternational",
"github_project": "rapidpro-flow-toolkit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Jinja2",
"specs": [
[
"~=",
"3.0.3"
]
]
},
{
"name": "networkx",
"specs": [
[
"~=",
"2.5.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"~=",
"1.8.2"
]
]
},
{
"name": "tablib",
"specs": [
[
">=",
"3.1.0"
]
]
},
{
"name": "openpyxl",
"specs": [
[
"~=",
"3.0.7"
]
]
},
{
"name": "google-api-python-client",
"specs": [
[
"~=",
"2.6.0"
]
]
},
{
"name": "google-auth-oauthlib",
"specs": [
[
"~=",
"0.4.4"
]
]
}
],
"lcname": "rpft"
}
JSON
