# pynubia
---
Nubia is a lightweight framework for building command-line applications with Python. It was originally designed for the “logdevice interactive shell (aka. `ldshell`)” at Facebook. Since then it was factored out to be a reusable component and several internal Facebook projects now rely on it as a quick and easy way to get an intuitive shell/cli application without too much boilerplate.
Nubia is built on top of [python-prompt-toolkit](https://github.com/jonathanslenders/python-prompt-toolkit) which is a fantastic toolkit for building interactive command-line applications.
_Disclaimer: Nubia is beta for non-ldshell use-cases. Some of the design decisions might sound odd but they fit the ldshell usecase perfectly. We are continuously making changes to make it more consistent and generic outside of the ldshell use-case. Until a fully stable release is published, use it on your own risk._
See the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.
If you are curious on the origins of the name, checkout [Nubia on Wikipedia](https://en.wikipedia.org/wiki/Nubia) with its unique and colourful architecture.
## Key Features
* Interactive mode that offers fish-style auto-completion
* CLI mode that gets generated from your functions and classes.
* Optional bash/zsh completions via an external utility ‘nubia-complete’ (experimental)
* A customisable status-bar in interactive mode.
* An optional IPython-based interactive shell
* Arguments with underscores are automatically hyphenated
* Python3 type annotations are used for input type validation
### Interactive mode
The interactive mode in Nubia is what makes it unique. It is very easy to build a unique shell for your program with zero overhead. The interactive shell in its simplistic form offers automatic completions for commands, sub-commands, arguments, and values. It also offers a great deal of control for developers to take control over auto-completions, even for commands that do not fall under the typical format. An example is the “select” command in ldshell which is expressed as a SQL-query. We expect that most use cases of Nubia will not need such control and the AutoCommand will be enough without further customisation.
If you start a nubia-based program without a command, it automatically starts an interactive shell. The interactive mode looks like this:
### Non-interactive mode
The CLI mode works exactly like any traditional unix-based command line utility.
Have your `@command` decorated function return an `int` to send that value as the Unix return code for your non interactive CLI.
## Examples
It starts with a function like this:
```py
import socket
import typing
from termcolor import cprint
from nubia import argument, command, context
@command
@argument("hosts", description="Hostnames to resolve", aliases=["i"])
@argument("bad_name", name="nice", description="testing")
async def lookup(hosts: typing.List[str], bad_name: int) -> int:
"""
This will lookup the hostnames and print the corresponding IP addresses
"""
ctx = context.get_context()
if not hosts:
cprint("No hosts supplied via --hosts")
return 1
print(f"hosts: {hosts}")
cprint(f"Verbose? {ctx.verbose}")
for host in hosts:
cprint(f"{host} is {socket.gethostbyname(host)}")
return 0
```
## Requirements
Nubia-based applications require Python 3.9+ and works with both Mac OS X or Linux. While in theory it should work on Windows, it has never been tried.
## Installing Nubia
Under construction
## Building Nubia from source
```bash
poetry build
```
## Running example in virtualenv:
_We recommend setting up a separate Python environment using a tool like virtualenv, pyenv-virtualenv, or `poetry shell`._
If you would like to run the example, install the dependencies and run the example module as a script.
```bash
poetry install
cd example
python -m nubia_example
```
To run the unit tests:
```bash
poetry run nosetests
```
## Getting Started
See the [getting started](GETTING_STARTED.md) guide to learn how to build a simple application with Nubia.
## License
Nubia is BSD licensed, as found in the LICENSE file.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/tmlaw/python-nubia",
"name": "pynubia",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "cli, shell, interactive, framework",
"author": "Travis Law",
"author_email": "tmlaw0182@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c5/2d/9e1a16ef635729ea4186a36f82e1d648a97477c3bada29817d930c2c9e59/pynubia-0.3.0.tar.gz",
"platform": null,
"description": "# pynubia\n\n---\n\nNubia is a lightweight framework for building command-line applications with Python. It was originally designed for the \u201clogdevice interactive shell (aka. `ldshell`)\u201d at Facebook. Since then it was factored out to be a reusable component and several internal Facebook projects now rely on it as a quick and easy way to get an intuitive shell/cli application without too much boilerplate.\n\nNubia is built on top of [python-prompt-toolkit](https://github.com/jonathanslenders/python-prompt-toolkit) which is a fantastic toolkit for building interactive command-line applications.\n\n_Disclaimer: Nubia is beta for non-ldshell use-cases. Some of the design decisions might sound odd but they fit the ldshell usecase perfectly. We are continuously making changes to make it more consistent and generic outside of the ldshell use-case. Until a fully stable release is published, use it on your own risk._\n\nSee the [CONTRIBUTING](CONTRIBUTING.md) file for how to help out.\n\nIf you are curious on the origins of the name, checkout [Nubia on Wikipedia](https://en.wikipedia.org/wiki/Nubia) with its unique and colourful architecture.\n\n## Key Features\n\n* Interactive mode that offers fish-style auto-completion\n* CLI mode that gets generated from your functions and classes.\n* Optional bash/zsh completions via an external utility \u2018nubia-complete\u2019 (experimental)\n* A customisable status-bar in interactive mode.\n* An optional IPython-based interactive shell\n* Arguments with underscores are automatically hyphenated\n* Python3 type annotations are used for input type validation\n\n### Interactive mode\nThe interactive mode in Nubia is what makes it unique. It is very easy to build a unique shell for your program with zero overhead. The interactive shell in its simplistic form offers automatic completions for commands, sub-commands, arguments, and values. It also offers a great deal of control for developers to take control over auto-completions, even for commands that do not fall under the typical format. An example is the \u201cselect\u201d command in ldshell which is expressed as a SQL-query. We expect that most use cases of Nubia will not need such control and the AutoCommand will be enough without further customisation.\n\nIf you start a nubia-based program without a command, it automatically starts an interactive shell. The interactive mode looks like this:\n\n![Interactive Demo](docs/interactive.gif?raw=true \"Interactive demo\")\n\n### Non-interactive mode\nThe CLI mode works exactly like any traditional unix-based command line utility.\n![Non-interactive Demo](docs/non_interactive.png?raw=true \"Non-interactive demo\")\n\nHave your `@command` decorated function return an `int` to send that value as the Unix return code for your non interactive CLI.\n\n## Examples\nIt starts with a function like this:\n```py\nimport socket\nimport typing\n\nfrom termcolor import cprint\nfrom nubia import argument, command, context\n\n@command\n@argument(\"hosts\", description=\"Hostnames to resolve\", aliases=[\"i\"])\n@argument(\"bad_name\", name=\"nice\", description=\"testing\")\nasync def lookup(hosts: typing.List[str], bad_name: int) -> int:\n \"\"\"\n This will lookup the hostnames and print the corresponding IP addresses\n \"\"\"\n ctx = context.get_context()\n\n if not hosts:\n cprint(\"No hosts supplied via --hosts\")\n return 1\n\n print(f\"hosts: {hosts}\")\n cprint(f\"Verbose? {ctx.verbose}\")\n\n for host in hosts:\n cprint(f\"{host} is {socket.gethostbyname(host)}\")\n\n return 0\n```\n\n## Requirements\n\nNubia-based applications require Python 3.9+ and works with both Mac OS X or Linux. While in theory it should work on Windows, it has never been tried.\n\n## Installing Nubia\n\nUnder construction\n\n## Building Nubia from source\n\n```bash\npoetry build\n```\n\n## Running example in virtualenv:\n\n_We recommend setting up a separate Python environment using a tool like virtualenv, pyenv-virtualenv, or `poetry shell`._\n\n\nIf you would like to run the example, install the dependencies and run the example module as a script.\n\n```bash\npoetry install\ncd example\npython -m nubia_example\n```\n\nTo run the unit tests:\n\n```bash\npoetry run nosetests\n```\n\n## Getting Started\n\nSee the [getting started](GETTING_STARTED.md) guide to learn how to build a simple application with Nubia.\n\n## License\nNubia is BSD licensed, as found in the LICENSE file.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A framework for building beautiful shells.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://gitlab.com/tmlaw/python-nubia",
"Repository": "https://gitlab.com/tmlaw/python-nubia"
},
"split_keywords": [
"cli",
" shell",
" interactive",
" framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "39e5c45aa5c7687ea606aa32c5ed74e827f2e08337efaeeb9be9dee76fed8992",
"md5": "8bb41f568ada31d7d41be55240402255",
"sha256": "52abf3407223842ceb9ec0dc341e35483cce1e72a00ee7e58fb208d667f037de"
},
"downloads": -1,
"filename": "pynubia-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8bb41f568ada31d7d41be55240402255",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 61151,
"upload_time": "2024-11-02T00:18:17",
"upload_time_iso_8601": "2024-11-02T00:18:17.318755Z",
"url": "https://files.pythonhosted.org/packages/39/e5/c45aa5c7687ea606aa32c5ed74e827f2e08337efaeeb9be9dee76fed8992/pynubia-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c52d9e1a16ef635729ea4186a36f82e1d648a97477c3bada29817d930c2c9e59",
"md5": "6d10f53a62fcf33400530f25c04c3308",
"sha256": "248b7f4422db3d0b2434940cc40cd6ffb00dd410068cc48210fa30d7f3278533"
},
"downloads": -1,
"filename": "pynubia-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "6d10f53a62fcf33400530f25c04c3308",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 44776,
"upload_time": "2024-11-02T00:18:19",
"upload_time_iso_8601": "2024-11-02T00:18:19.960322Z",
"url": "https://files.pythonhosted.org/packages/c5/2d/9e1a16ef635729ea4186a36f82e1d648a97477c3bada29817d930c2c9e59/pynubia-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-02 00:18:19",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "tmlaw",
"gitlab_project": "python-nubia",
"lcname": "pynubia"
}
JSON