# AWS Cloudwatch Insights
* Free software: Apache Software License 2.0
Though OpenAPI documented services offer a nice UI to test the endpoints, I couldn't find a good command line tool for
this. Here I created something that works nicely with zsh completions. If you have the OpenAPI spec available, you
put it in your `~/.carl/open_api`. Then parameters can be passed as `+{param-name}`, with tab-completions, and then
these are passed to `curl`.
There is no way that this covers all the cases for the OpenAPI spec, but it hopefully covers the vast majority people
of cases people actually encounter.
### Installation
```shell
# globally
% pipx install 'curl_arguments_url'
# or in a particular virtual env
% pip install 'curl_arguments_url'
# to get the completions to work, add the following to your .zshrc
eval "$(carl utils zsh-print-script)"
# And copy the OpenAPI spec into ~/.carl/open_api to get the completions and curl-building working
% cp open_api-spec.yml ~/.carl/open_api
# if parsing of the open_api files is too slow for you, you can try installing the ryaml (Rust Yaml) extension. I
# didn't include this by default because I'm afraid it might not install correctly on certain systems, but it's much
# faster
% pipx install 'curl_arguments_url[ryaml]'
```
### Examples
These examples use [tests/resources/open_api/openapi-demo.yml](tests/resources/open_api/openapi-demo.yml)
* Basic GET
```shell
% carl http://demo.io/v0/entities/\{path-item\} GET +path-item ID +query-item query-this --no-run --print-cmd
curl -X GET 'http://demo.io/v0/entities/ID?query-item=query-this'
```
* More complicated POST command
```shell
% carl http://demo.io/v0/entities/\{path-item\} POST \
+path-item ID +field-one value +field-two an array of values \
+field-three '{"complex":["sub","value"]}' \
+field-header 'Header Param Value' \
--no-run --print-cmd \
-- --silent # you can get other arguments passed to curl at the end, like this
# the output wouldn't be this nicely formatted, but so you can see what curl command would be run
curl -X POST http://demo.io/v0/entities/ID \
-H 'field-header: Header Param Value' -H 'Content-Type: application/json' \
--data-binary \
'{"field-one": "value", "field-two": ["an", "array", "of", "values"], "field-three": {"complex": ["sub", "value"]}}' \
--silent
```
* Values are cached for completion by param name.
* These cached values can be managed with the `carl utils cached-values` utility:
```shell
% carl utils cached-values --help
usage: carl utils cached-values [-h] {params,ls,rm,add} ...
positional arguments:
{params,ls,rm,add}
params List all the param names that have values cached
ls List all the values cached for a particular param
rm Remove a value for an param from the cache for completions
add Add one or more values for a param to the cache
options:
-h, --help show this help message and exit
```
* Help is generated from the OpenAPI spec for your reference
```text
% carl --help
usage: carl [-h] {utils,http://demo.io/v0/entities/{path-item},http://demo.io/v0/restricted,http://demo.io/v0/other,http://demo.io/v0/endpoints} ...
A Utility to cleanly take command-line arguments, for an endpoint you have the
OpenAPI specification for, and convert them into an appropriate curl command.
Spec files should be in /root/.carl/open_api directory or directory defined by
env variables (See below)
positional arguments:
{utils,http://demo.io/v0/entities/{path-item},http://demo.io/v0/restricted,http://demo.io/v0/other,http://demo.io/v0/endpoints}
utils Utilities
http://demo.io/v0/entities/{path-item}
Demo Entity Endpoint
http://demo.io/v0/restricted
A Restricted Endpoint
http://demo.io/v0/other
Another Endpoint
http://demo.io/v0/endpoints
Yet Another Endpoint
options:
-h, --help show this help message and exit
Environment Variables:
CARL_DIR: Directory which contains files for carl. Default: ~/.carl
CARL_OPEN_API_DIR: Directory containing the OpenApi specifications and
Yaml files. Default: $CARL_DIR/open_api
CARL_CACHE_DIR: Directory containing the cache. Default $CARL_DIR/cache
```
For a specific endpoint:
```text
% carl http://demo.io/v0/entities/\{path-item\} POST --help
usage: carl http://demo.io/v0/entities/{path-item} POST [-h] [-p] [-n] [-R] [-b BODY_JSON] [+field-header FIELD_HEADER] [+field-one FIELD_ONE]
[+field-two FIELD_TWO [FIELD_TWO ...]] [+field-three FIELD_THREE] +path-item PATH_ITEM
[passed_to_curl ...]
Demo Post Command
positional arguments:
passed_to_curl Extra argument passed to curl, often after "--"
options:
-h, --help show this help message and exit
-p, --print-cmd Print the resulting curl command to standard out
-n, --no-run Don't run the curl command. Useful with -p
-R, --no-requires Don't check to see if required parameter values are missing or if values are one of the enumerated values
-b BODY_JSON, --body-json BODY_JSON, --body BODY_JSON
Base json object to send in the body. Required body params are still required unless -R option passed. Useful for dealing with incomplete specs.
+field-header FIELD_HEADER
Header Param
+field-one FIELD_ONE Demo Body String Field
+field-two FIELD_TWO [FIELD_TWO ...]
Demo Body Array Field
+field-three FIELD_THREE
Demo Body Complex Field
+path-item PATH_ITEM
```
* Generic Optional Args:
```text
-p, --print-cmd Print the resulting curl command to standard out
-n, --no-run Don't run the curl command. Useful with -p
-R, --no-requires Don't check to see if required parameter values are missing or if values are one of the enumerated values
-b BODY_JSON, --body-json BODY_JSON, --body BODY_JSON
Base json object to send in the body. Required body params are still required unless -R option passed. Useful for dealing with incomplete specs.
```
* Relevant Environment Variables
```text
CARL_DIR: Directory which contains files for carl. Default: ~/.carl
CARL_OPEN_API_DIR: Directory containing the OpenApi specifications and
Yaml files. Default: $CARL_DIR/open_api
CARL_CACHE_DIR: Directory containing the cache. Default $CARL_DIR/cache
```
### Hints for finding OpenAPI specs
The spec you're interested in might be on https://app.swaggerhub.com/. Also, sometimes the doc/sandbox page, for an
api, which gives you a gui for interacting with the api, loads the swagger spec in the background. You can see this
if you open the developer tools in Chrome under Network
## Development
Requires make:
```shell
# setting up dev environment
$ make develop
# run tests
$ make test
# ... or
$ pytest
# run tests for all environments
$ make test-all
```
No CI/CD or coverage yet
## To Do/Future Features
* A `--query` option for adding query parameters directly
* Some sort of hook infrastructure, so you could do things like have custom-completions for certain parameters or
automatically add a particular env variable as an auth header
* Support file uploading and downloading
* Utilize the authorization part of the OpenAPI spec
* Better support for nested json objects in the body, so that `+param.sub-param value` would set
`{"param"{"sub-param":"value"}}`
* Maybe support older versions of Swagger/OpenApi
* Speaking of which, in the code I sometimes use the term "swagger" and sometimes "open_api". I should make this
consistent.
* Support bash and fish. With how I implemented this, I thought it would be easy to implement bash. But the way bash
parses and escapes arguments passed to the completion function made it surprisingly challenging. The
`bash-completion` branch has my so-far attempts to deal with these issues. It might be close to done, or there
might be a slew of other issues I haven't realized yet.
## Credits
This package was created with _cookiecutter_ and the `audreyr/cookiecutter-pypackage` project template.
Raw data
{
"_id": null,
"home_page": "https://github.com/valmikirao/curl_arguments_url",
"name": "curl-arguments-url",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "curl_arguments_url,carl,curl,zsh,completions,swagger,openapi",
"author": "Valmiki Rao",
"author_email": "valmikirao@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d2/4b/7d8a7399fdbad2fbe52286aa347f3d6e45ab5af10d91516c83d4bf68d190/curl_arguments_url-0.1.4.tar.gz",
"platform": null,
"description": "# AWS Cloudwatch Insights\n\n\n\n\n\n* Free software: Apache Software License 2.0\n\n\n\nThough OpenAPI documented services offer a nice UI to test the endpoints, I couldn't find a good command line tool for\nthis. Here I created something that works nicely with zsh completions. If you have the OpenAPI spec available, you\nput it in your `~/.carl/open_api`. Then parameters can be passed as `+{param-name}`, with tab-completions, and then\nthese are passed to `curl`.\n\nThere is no way that this covers all the cases for the OpenAPI spec, but it hopefully covers the vast majority people\nof cases people actually encounter.\n\n### Installation\n\n```shell\n# globally\n% pipx install 'curl_arguments_url'\n# or in a particular virtual env\n% pip install 'curl_arguments_url'\n\n# to get the completions to work, add the following to your .zshrc\neval \"$(carl utils zsh-print-script)\"\n\n# And copy the OpenAPI spec into ~/.carl/open_api to get the completions and curl-building working\n% cp open_api-spec.yml ~/.carl/open_api\n\n# if parsing of the open_api files is too slow for you, you can try installing the ryaml (Rust Yaml) extension. I\n# didn't include this by default because I'm afraid it might not install correctly on certain systems, but it's much\n# faster\n% pipx install 'curl_arguments_url[ryaml]'\n \n```\n\n### Examples\n\nThese examples use [tests/resources/open_api/openapi-demo.yml](tests/resources/open_api/openapi-demo.yml)\n\n* Basic GET\n\n```shell\n% carl http://demo.io/v0/entities/\\{path-item\\} GET +path-item ID +query-item query-this --no-run --print-cmd\ncurl -X GET 'http://demo.io/v0/entities/ID?query-item=query-this'\n```\n\n* More complicated POST command\n\n```shell\n% carl http://demo.io/v0/entities/\\{path-item\\} POST \\\n +path-item ID +field-one value +field-two an array of values \\\n +field-three '{\"complex\":[\"sub\",\"value\"]}' \\\n +field-header 'Header Param Value' \\\n --no-run --print-cmd \\\n -- --silent # you can get other arguments passed to curl at the end, like this\n# the output wouldn't be this nicely formatted, but so you can see what curl command would be run\ncurl -X POST http://demo.io/v0/entities/ID \\\n -H 'field-header: Header Param Value' -H 'Content-Type: application/json' \\\n --data-binary \\\n '{\"field-one\": \"value\", \"field-two\": [\"an\", \"array\", \"of\", \"values\"], \"field-three\": {\"complex\": [\"sub\", \"value\"]}}' \\\n --silent\n ```\n\n* Values are cached for completion by param name.\n\n\n\n* These cached values can be managed with the `carl utils cached-values` utility:\n\n```shell\n% carl utils cached-values --help\nusage: carl utils cached-values [-h] {params,ls,rm,add} ...\n\npositional arguments:\n {params,ls,rm,add}\n params List all the param names that have values cached\n ls List all the values cached for a particular param\n rm Remove a value for an param from the cache for completions\n add Add one or more values for a param to the cache\n\noptions:\n -h, --help show this help message and exit\n```\n\n* Help is generated from the OpenAPI spec for your reference\n\n```text\n% carl --help\nusage: carl [-h] {utils,http://demo.io/v0/entities/{path-item},http://demo.io/v0/restricted,http://demo.io/v0/other,http://demo.io/v0/endpoints} ...\n\nA Utility to cleanly take command-line arguments, for an endpoint you have the\nOpenAPI specification for, and convert them into an appropriate curl command.\nSpec files should be in /root/.carl/open_api directory or directory defined by\nenv variables (See below)\n\npositional arguments:\n {utils,http://demo.io/v0/entities/{path-item},http://demo.io/v0/restricted,http://demo.io/v0/other,http://demo.io/v0/endpoints}\n utils Utilities\n http://demo.io/v0/entities/{path-item}\n Demo Entity Endpoint\n http://demo.io/v0/restricted\n A Restricted Endpoint\n http://demo.io/v0/other\n Another Endpoint\n http://demo.io/v0/endpoints\n Yet Another Endpoint\n\noptions:\n -h, --help show this help message and exit\n\nEnvironment Variables:\n CARL_DIR: Directory which contains files for carl. Default: ~/.carl\n CARL_OPEN_API_DIR: Directory containing the OpenApi specifications and\n Yaml files. Default: $CARL_DIR/open_api\n CARL_CACHE_DIR: Directory containing the cache. Default $CARL_DIR/cache\n```\n\nFor a specific endpoint:\n```text\n% carl http://demo.io/v0/entities/\\{path-item\\} POST --help\nusage: carl http://demo.io/v0/entities/{path-item} POST [-h] [-p] [-n] [-R] [-b BODY_JSON] [+field-header FIELD_HEADER] [+field-one FIELD_ONE]\n [+field-two FIELD_TWO [FIELD_TWO ...]] [+field-three FIELD_THREE] +path-item PATH_ITEM\n [passed_to_curl ...]\n\nDemo Post Command\n\npositional arguments:\n passed_to_curl Extra argument passed to curl, often after \"--\"\n\noptions:\n -h, --help show this help message and exit\n -p, --print-cmd Print the resulting curl command to standard out\n -n, --no-run Don't run the curl command. Useful with -p\n -R, --no-requires Don't check to see if required parameter values are missing or if values are one of the enumerated values\n -b BODY_JSON, --body-json BODY_JSON, --body BODY_JSON\n Base json object to send in the body. Required body params are still required unless -R option passed. Useful for dealing with incomplete specs.\n +field-header FIELD_HEADER\n Header Param\n +field-one FIELD_ONE Demo Body String Field\n +field-two FIELD_TWO [FIELD_TWO ...]\n Demo Body Array Field\n +field-three FIELD_THREE\n Demo Body Complex Field\n +path-item PATH_ITEM\n```\n\n* Generic Optional Args:\n\n```text\n -p, --print-cmd Print the resulting curl command to standard out\n -n, --no-run Don't run the curl command. Useful with -p\n -R, --no-requires Don't check to see if required parameter values are missing or if values are one of the enumerated values\n -b BODY_JSON, --body-json BODY_JSON, --body BODY_JSON\n Base json object to send in the body. Required body params are still required unless -R option passed. Useful for dealing with incomplete specs.\n```\n\n* Relevant Environment Variables\n\n```text\n CARL_DIR: Directory which contains files for carl. Default: ~/.carl\n CARL_OPEN_API_DIR: Directory containing the OpenApi specifications and\n Yaml files. Default: $CARL_DIR/open_api\n CARL_CACHE_DIR: Directory containing the cache. Default $CARL_DIR/cache\n```\n\n### Hints for finding OpenAPI specs\n\nThe spec you're interested in might be on https://app.swaggerhub.com/. Also, sometimes the doc/sandbox page, for an\napi, which gives you a gui for interacting with the api, loads the swagger spec in the background. You can see this\nif you open the developer tools in Chrome under Network\n\n## Development\n\nRequires make:\n\n```shell\n# setting up dev environment\n$ make develop\n\n# run tests\n$ make test\n# ... or\n$ pytest\n\n# run tests for all environments\n$ make test-all\n\n```\n\nNo CI/CD or coverage yet\n\n## To Do/Future Features\n\n* A `--query` option for adding query parameters directly\n* Some sort of hook infrastructure, so you could do things like have custom-completions for certain parameters or\n automatically add a particular env variable as an auth header\n* Support file uploading and downloading\n* Utilize the authorization part of the OpenAPI spec\n* Better support for nested json objects in the body, so that `+param.sub-param value` would set\n `{\"param\"{\"sub-param\":\"value\"}}`\n* Maybe support older versions of Swagger/OpenApi\n* Speaking of which, in the code I sometimes use the term \"swagger\" and sometimes \"open_api\". I should make this\n consistent.\n* Support bash and fish. With how I implemented this, I thought it would be easy to implement bash. But the way bash\n parses and escapes arguments passed to the completion function made it surprisingly challenging. The\n `bash-completion` branch has my so-far attempts to deal with these issues. It might be close to done, or there\n might be a slew of other issues I haven't realized yet.\n\n## Credits\n\nThis package was created with _cookiecutter_ and the `audreyr/cookiecutter-pypackage` project template.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Curl with Arguments for Url",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/valmikirao/curl_arguments_url"
},
"split_keywords": [
"curl_arguments_url",
"carl",
"curl",
"zsh",
"completions",
"swagger",
"openapi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a3432c076be900ca093640587abf11c3c9e10e4c875e50057f83d693b9130a5",
"md5": "56fae3b69e65ff16238914a5ea49afec",
"sha256": "005e4adc1de79f87df954240e715ba7a410c39006fc561c1d1ad0655f28e1ec2"
},
"downloads": -1,
"filename": "curl_arguments_url-0.1.4-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "56fae3b69e65ff16238914a5ea49afec",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 23390,
"upload_time": "2023-05-31T17:57:03",
"upload_time_iso_8601": "2023-05-31T17:57:03.378953Z",
"url": "https://files.pythonhosted.org/packages/9a/34/32c076be900ca093640587abf11c3c9e10e4c875e50057f83d693b9130a5/curl_arguments_url-0.1.4-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d24b7d8a7399fdbad2fbe52286aa347f3d6e45ab5af10d91516c83d4bf68d190",
"md5": "af392f4a1565d22c229ee5483a413819",
"sha256": "ab9e35e932cfb9b1e55a04a328dfe3eb3c27faa2029d0d3d9e5c23843b39cb7d"
},
"downloads": -1,
"filename": "curl_arguments_url-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "af392f4a1565d22c229ee5483a413819",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 24628,
"upload_time": "2023-05-31T17:57:05",
"upload_time_iso_8601": "2023-05-31T17:57:05.828922Z",
"url": "https://files.pythonhosted.org/packages/d2/4b/7d8a7399fdbad2fbe52286aa347f3d6e45ab5af10d91516c83d4bf68d190/curl_arguments_url-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 17:57:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "valmikirao",
"github_project": "curl_arguments_url",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "curl-arguments-url"
}
JSON
