# -*- coding: utf-8 -*-
from setuptools import setup

packages = \
['zum', 'zum.cli', 'zum.configs', 'zum.requests']

package_data = \
{'': ['*']}

install_requires = \
['httpx>=0.17.1,<0.18.0', 'tomlkit>=0.7.0,<0.8.0']

entry_points = \
{'console_scripts': ['zum = zum.cli.core:dispatcher']}

setup_kwargs = {
    'name': 'zum',
    'version': '0.3.0',
    'description': 'Stop writing scripts to interact with your APIs. Call them as CLIs instead.',
    'long_description': '<p align="center">\n    <a href="https://github.com/daleal/zum">\n        <img src="https://zum.daleal.dev/assets/images/zum-300x300.png">\n    </a>\n</p>\n\n<h1 align="center">Zum</h1>\n\n<p align="center">\n    <em>\n        Stop writing scripts to interact with your APIs. Call them as CLIs instead.\n    </em>\n</p>\n\n<p align="center">\n<a href="https://pypi.org/project/zum" target="_blank">\n    <img src="https://img.shields.io/pypi/v/zum?label=version&logo=python&logoColor=%23fff&color=306998" alt="PyPI - Version">\n</a>\n\n<a href="https://github.com/daleal/zum/actions?query=workflow%3Atests" target="_blank">\n    <img src="https://img.shields.io/github/workflow/status/daleal/zum/tests?label=tests&logo=python&logoColor=%23fff" alt="Tests">\n</a>\n\n<a href="https://codecov.io/gh/daleal/zum" target="_blank">\n    <img src="https://img.shields.io/codecov/c/gh/daleal/zum?label=coverage&logo=codecov&logoColor=ffffff" alt="Coverage">\n</a>\n\n<a href="https://github.com/daleal/zum/actions?query=workflow%3Alinters" target="_blank">\n    <img src="https://img.shields.io/github/workflow/status/daleal/zum/linters?label=linters&logo=github" alt="Linters">\n</a>\n</p>\n\n**Zum** (German word roughly meaning "_to the_" or "_to_" depending on the context, pronounced `/tsʊm/`) is a tool that lets you describe a web API using a [TOML](https://toml.io/en/) file and then interact with that API using your command line. This means that **the days of writing custom scripts to help you interact and develop each of your APIs are over**. Just create a `zum.toml`, describe your API and forget about maintaining more code!\n\n## Why Zum?\n\nWhile there are tools out there with goals similar to `zum`, the scopes are quite different. The common contenders are [OpenAPI](http://spec.openapis.org/oas/v3.0.3)-based tools (like [SwaggerUI](https://swagger.io/tools/swagger-ui/)) and [cURL](https://curl.se/). To me, using an OpenAPI-based documentation tool is essential on any large enough API, but the description method is **very** verbose and quite complex, so often times it is added once the API has quite a few endpoints. On the other hand, cURL gets very verbose and tedious very fast when querying APIs, so I don\'t like to use it when developing my APIs. As a comparison, here\'s a `curl` command to query a local endpoint with a JSON body:\n\n```sh\ncurl --header "Content-Type: application/json" \\\n    --request POST \\\n    --data \'{"name": "Dani", "city": "Santiago"}\' \\\n    http://localhost:8000/living-beings\n```\n\nAnd here is the `zum` command to achieve the same result:\n\n```sh\nzum create application/json Dani Santiago\n```\n\nNow, imagine having to run this command hundreads of times during API development changing only the values on the request body, for example. You can see how using cURL is **not ideal**.\n\nThe [complete documentation](https://zum.daleal.dev/docs/) is available on the [official website](https://zum.daleal.dev/).\n\n## Installation\n\nInstall using pip!\n\n```sh\npip install zum\n```\n\n## Usage\n\n### Basic Usage\n\nThe basic principle is simple:\n\n1. Describe your API using a `zum.toml` file.\n2. Use the `zum` CLI to interact with your API.\n\nWe get more _in-depth_ with how to structure the `zum.toml` file and how to use the `zum` CLI on [the complete documentation](https://zum.daleal.dev/docs/), but for now let\'s see a very basic example. Imagine that you are developing an API that gets the URL of [a song on YouTube](https://youtu.be/6xlsR1c8yh4). This API, for now, has only 1 endpoint: `GET /song` (clearly a [WIP](https://www.urbandictionary.com/define.php?term=Wip)). To describe your API, you would have to write a `zum.toml` file similar to this one:\n\n```toml\n[metadata]\nserver = "http://localhost:8000"\n\n[endpoints.dada]\nroute = "/song"\nmethod = "get"\n```\n\nNow, to get your song\'s URL, all you need to do is to run:\n\n```sh\nzum dada\n```\n\nNotice that, after the `zum` command, we passed an argument, that in this case was `dada`. This argument tells `zum` that it should interact with the endpoint described on the `dada` endpoint section, denoted by the header `[endpoints.dada]`. As a rule, to access an endpoint described by the header `[endpoints.{my-endpoint-name}]`, you will call the `zum` command with the `{my-endpoint-name}` argument:\n\n```sh\nzum {my-endpoint-name}\n```\n\n### `params`, `headers` and `body`\n\n**Beware!** There are some nuances on these attribute definitions, so reading [the complete documentation](https://zum.daleal.dev/docs/) is **highly recommended**.\n\n#### The `params` of an endpoint\n\nOn the previous example, the `route` was static, which means that `zum` will **always** query the same route. For some things, this might not be the best of ideas (for example, for querying entities on REST APIs), and you might want to interpolate a value on the `route` string. Let\'s say that there\'s a collection of songs, and you wanted to get the song with `id` _57_. Your endpoint definition should look like the following:\n\n```toml\n[endpoints.get-song]\nroute = "/songs/{id}"\nmethod = "get"\nparams = ["id"]\n```\n\nAs you can see, the element inside `params` matches the element inside the brackets on the `route`. This means that whatever parameter you pass to the `zum` CLI, it will be replaced on the `route` _on-demand_:\n\n```sh\nzum get-song 57\n```\n\nNow, `zum` will send a `GET` HTTP request to `http://localhost:8000/songs/57`. Pretty cool!\n\n#### The `headers` of an endpoint\n\nThe `headers` are defined **exactly** the same as the `params`. Let\'s see a small example to illustrate how to use them. Imagine that you have an API that requires [JWT](https://jwt.io/introduction) authorization to `GET` the songs of its catalog. Let\'s define that endpoint:\n\n```toml\n[endpoints.get-authorized-catalog]\nroute = "/catalog"\nmethod = "get"\nheaders = ["Authorization"]\n```\n\nNow, to acquire the catalog, we would need to run:\n\n```sh\nzum get-authorized-catalog "Bearer super-secret-token"\n```\n\n> ⚠ **Warning**: Notice that, for the first time, we surrounded something with quotes on the CLI. The reason we did this is that, without the quotes, the console has no way of knowing if you want to pass a parameter with a space in the middle or if you want to pass multiple parameters, so it defaults to receiving the words as multiple parameters. To stop this from happening, you can surround the string in quotes, and now the whole string will be interpreted as only one parameter with the space in the middle of the string. This will be handy on future examples, so **keep it in mind**.\n\nThis will send a `GET` request to `http://localhost:8000/catalog` with the following headers:\n\n```json\n{\n    "Authorization": "Bearer super-secret-token"\n}\n```\n\nAnd now you have your authorization-protected music catalog!\n\n#### The `body` of an endpoint\n\nJust like `params` and `headers`, the `body` (the body of the request) gets defined as an array:\n\n```toml\n[endpoints.create-living-being]\nroute = "/living-beings"\nmethod = "post"\nbody = ["name", "city"]\n```\n\nTo run this endpoint, you just need to run:\n\n```sh\nzum create-living-being Dani Santiago\n```\n\nThis will send a `POST` request to `http://localhost:8000/living-beings` with the following request body:\n\n```json\n{\n    "name": "Dani",\n    "city": "Santiago"\n}\n```\n\n**Notice that you can also cast the parameters to different types**. You can read more about this on the complete documentation\'s section about [the request body](https://zum.daleal.dev/docs/config-file.html#the-body-of-an-endpoint).\n\n#### Combining `params`, `headers` and `body`\n\nOf course, sometimes you need to use some `params`, some `headers` **and** a `body`. For example, if you wanted to create a song inside an authorization-protected album (a _nested entity_), you would need to use the album\'s id as a `param`, the "Authorization" key inside the `headers` to get the authorization and the new song\'s data as the `body`. For this example, the song has a `name` (which is a string) and a `duration` in seconds (which is an integer). Let\'s describe this situation!\n\n```toml\n[endpoints.create-song]\nroute = "/albums/{id}/songs"\nmethod = "post"\nparams = ["id"]\nheaders = ["Authorization"]\nbody = [\n    "name",\n    { name = "duration", type = "integer" }\n]\n```\n\nNow, you can call the endpoint using:\n\n```sh\nzum create-song 8 "Bearer super-secret-token" "Con Altura" 161\n```\n\nThis will call `POST /albums/8/songs` with the following headers:\n\n```json\n{\n    "Authorization": "Bearer super-secret-token"\n}\n```\n\nAnd the following request body:\n\n```json\n{\n    "name": "Con Altura",\n    "duration": 161\n}\n```\n\nAs you can probably tell, `zum` receives the `params` first on the CLI, then the `headers` and then the `body`. In _pythonic_ terms, what `zum` does is that it kind of _unpacks_ the three arrays consecutively, something like the following:\n\n```py\narguments = [*params, *headers, *body]\nzum(arguments)\n```\n\n## Developing\n\nClone the repository:\n\n```sh\ngit clone https://github.com/daleal/zum.git\n\ncd zum\n```\n\nRecreate environment:\n\n```sh\nmake get-poetry\nmake build-env\n```\n\nRun the linters:\n\n```sh\nmake black flake8 isort mypy pylint\n```\n\nRun the tests:\n\n```sh\nmake tests\n```\n\n## Resources\n\n- [Official Website](https://zum.daleal.dev/)\n- [Issue Tracker](https://github.com/daleal/zum/issues/)\n- [Contributing Guidelines](.github/CONTRIBUTING.md)\n',
    'author': 'Daniel Leal',
    'author_email': 'dlleal@uc.cl',
    'maintainer': 'Daniel Leal',
    'maintainer_email': 'dlleal@uc.cl',
    'url': 'https://zum.daleal.dev/',
    'packages': packages,
    'package_data': package_data,
    'install_requires': install_requires,
    'entry_points': entry_points,
    'python_requires': '>=3.6,<4.0',
}


setup(**setup_kwargs)
