binarylane-cli 0.15.0__tar.gz → 0.15.1__tar.gz

{binarylane_cli-0.15.0 → binarylane_cli-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: binarylane-cli
-Version: 0.15.0
+Version: 0.15.1
 Summary: 
 Author: Nathan O'Sullivan
 Author-email: nathan.osullivan@mammoth.com.au

{binarylane_cli-0.15.0 → binarylane_cli-0.15.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "binarylane-cli"
-version = "0.15.0"
+version = "0.15.1"
 description = ""
 authors = ["Nathan O'Sullivan <nathan.osullivan@mammoth.com.au>"]
 readme = "README.md"

{binarylane_cli-0.15.0 → binarylane_cli-0.15.1}/setup.py

@@ -73,7 +73,7 @@ entry_points = \
 
 setup_kwargs = {
     'name': 'binarylane-cli',
-    'version': '0.15.0',
+    'version': '0.15.1',
     'description': '',
     'long_description': '# `bl`: BinaryLane command-line interface\n\n```\n$ bl --help\nusage: bl [OPTIONS] COMMAND\n\nbl is a command-line interface for the BinaryLane API\n\nOptions:\n  --help                Display available commands and descriptions\n\nAvailable Commands:\n    account             Access account commands\n    action              Access action commands\n    configure           Configure access to BinaryLane API\n    domain              Access domain commands\n    image               Access image commands\n    load-balancer       Access load-balancer commands\n    region              Access region commands\n    server              Access server commands\n    size                Access size commands\n    software            Access software commands\n    ssh-key             Access ssh-key commands\n    version             Show the current version\n    vpc                 Access vpc commands\n```\n\n## Installation\n\n`bl` requires Python 3.7 or later and has been tested on a variety of Linux\ndistributions, Windows and Mac OSX. To install:\n\n```\npip install binarylane-cli\n```\n\n### Portable install (without Python)\n\nThe [releases page](https://github.com/binarylane/binarylane-cli/releases) has\na standalone `bl.exe` for use on Windows.\n\n\n## Getting Started\n\nThe BinaryLane CLI program is invoked by running `bl` (or `bl.exe` on Windows).\nTo use `bl` you must configure the program with a BinaryLane customer access\ntoken.\n\n 1. To start the configuration process, run:\n```\nbl configure\n```\n\n 2. A prompt will be shown requesting access token. Go to [Developer API](https://home.binarylane.com.au/api-info) section of BinaryLane website and select **+ Create Token**, enter a name such as *CLI* and **Create**. \n\n 3. Copy the displayed token and paste at the `bl` *Enter your API access token:*\nprompt.\n\n 4. To confirm token is working correctly, use `bl` to display BinaryLane account details:\n```\nbl account get\n``` \n\n## Usage\n\n`bl` provides commands to access all functionality provided by the [BinaryLane\nAPI](https://api.binarylane.com.au/reference/), organised into a *command\ntree*. The general form for invoking an command is `bl NOUN [NOUN] VERB`.\nFor example:\n\n - `bl server list`: Displays list of servers\n - `bl domain record create`: Create a DNS record\n\nThe available commands at each level of the tree are displayed by running `bl`\nwith no arguments:\n\n```\n$ bl\n\nusage: bl [OPTIONS] COMMAND\n\nbl is a command-line interface for the binaryLane API\n\nOptions:\n  --help                Display available commands and descriptions\n\nAvailable Commands:\n    account             Access account commands\n    action              Access action commands\n    configure           Configure access to binaryLane API\n    domain              Access domain commands\n    image               Access image commands\n    load-balancer       Access load-balancer commands\n    region              Access region commands\n    server              Access server commands\n    size                Access size commands\n    software            Access software commands\n    ssh-key             Access ssh-key commands\n    version             Show the current version\n    vpc                 Access vpc commands\n```\n\nTo see the available commands within the tree:\n\n```\nbl NOUN [NOUN]\n```\n\nFor example:\n\n```\n$ bl domain\nusage: bl domain [OPTIONS] COMMAND\n\nAccess domain commands\n\nOptions:\n  --help                Display available commands and descriptions\n\nAvailable Commands:\n    create              Create a new domain\n    delete              Delete an existing domain\n    get                 Fetch an existing domain\n    list                List all domains\n    nameservers         Access domain nameservers commands\n    record              Access domain record commands\n```\n\nTo see the required arguments and optional parameters for a command:\n\n```\nbl NOUN [NOUN] VERB --help\n```\n\nFor example:\n\n```\n$ bl domain create --help\nusage: bl domain create [OPTIONS] --name NAME [PARAMETERS]\n\nCreate a New Domain\n\nOptions:\n  --help                Display command options and descriptions\n  --curl                Display API request as a \'curl\' command-line\n  --no-header           Display columns without field labels\n  --output OUTPUT       Desired output format [plain, table, tsv, json] (Default: "table")\n\nArguments:\n  --name NAME           The domain name to add to the DNS management system.\n\nParameters:\n  --ip-address IP_ADDRESS\n                        An optional IPv4 address that will be used to create an A record for the root domain.\n```\n\n### Walkthrough: Creating a server\n\nServer creation is provided by the `bl server create` command. Use `--help` to\nview all arguments and parameters:\n\n```\n$ bl server list --help\nusage: bl server create [OPTIONS] --size SIZE --image IMAGE --region REGION [PARAMETERS]\n\nCreate a new server.\n\nOptions:\n  --help                Display command options and descriptions\n  --curl                Display API request as a \'curl\' command-line\n  --no-header           Display columns without field labels\n  --output OUTPUT       Desired output format [plain, table, tsv, json] (Default: "table")\n  --async               Do not wait for requested action to complete\n  --quiet               Do not show progress while waiting for requested action to complete\n\nArguments:\n  --size SIZE           The slug of the selected size.\n  --image IMAGE         The slug or id of the selected operating system.\n  --region REGION       The slug of the selected region.\n\nParameters:\n  --name NAME           The hostname of your server, such as vps01.yourcompany.com. If not\n                        provided, the server will be created with a random name.\n  --backups, --no-backups\n                        If true this will enable two daily backups for the server.\n                        Options.daily_backups will override this value if provided. Setting\n                        this to false has no effect.\n  --ipv6, --no-ipv6     If true this will enable IPv6 for this server.\n  --ssh-keys [SSH_KEYS [SSH_KEYS ...]]\n                        This may be either the SSH keys Ids or fingerprints. If this is null\n                        or not provided any SSH keys that have been marked as default will be\n                        deployed (if the operating system supports SSH keys). Submit an empty\n                        array to disable deployment of default keys.\n  --password PASSWORD   If this is provided the default remote user account\'s password will be\n                        set to this value. If this is null a random password will be generated\n                        and emailed to the account email address.\n  <additional parameters omitted for brevity>\n```\n\nIn the help displayed by `bl`, **Arguments** are required and **Parameters**\nare optional. For the `bl server list` command `--size SIZE`, `--image IMAGE`,\nand `--region REGION` are required. A list of available choices for each can be\ndisplayed by running:\n\n```\nbl size list\nbl image list\nbl region list\n```\n\nFor example, to create a minimum-sized Ubuntu 22.04 LTS server in Sydney using\nSSH public key authentication:\n\n```\n$ bl server create --size std-min --image ubuntu-22.04-lts --region syd\ncompleted.\n┌───────────────────────────┬─────────────────────────────────────────────────────────────────────────────────────┐\n│ name                      │ value                                                                               │\n├───────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────┤\n│ id                        │ 210658                                                                              │\n│ name                      │ giant-rudolf.bnr.la                                                                 │\n│ memory                    │ 1024                                                                                │\n│ vcpus                     │ 1                                                                                   │\n│ disk                      │ 20                                                                                  │\n│ created_at                │ 2023-01-20T02:02:32+00:00                                                           │\n│ status                    │ new                                                                                 │\n│ region                    │ Sydney                                                                              │\n│ image                     │ 20.04 LTS                                                                           │\n│ size                      │ std-min                                                                             │\n│ size_slug                 │ std-min                                                                             │\n│ networks                  │ v4: [{\'ip_address\': \'175.45.180.1\',  \'type\': \'public\', \'netmask\': \'255.255.255.0... │\n  <additional rows omitted for brevity>\n└───────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Server passwords\n\nThe use of SSH public key authentication is strongly recommended where\npossible. When public key authentication is not suitable or the image being\ndeployed does not support SSH public key authentication (e.g. Windows Server),\ncommands such as `bl server create` and `bl server action password-reset` have\nan optional `--password PASSWORD` parameter that specifies the password to use.\n\nFor example, to create a server per the previous example with password\nauthentication:\n\n```\n$ bl server create --size std-min --image ubuntu-22.04-lts --region syd --password \'qq7s6GYZgbiVG3\'\n```\n\nUpon completion, the root password for the server in this example would be `qq7s6GYZgbiVG3`.\n\n:warning: **Internet-connected servers with password-based authentication enabled\nmust have a strong, randomly generated password.** Brute-force login attempts\nare pervasive on the public internet: if a server password is not randomly\ngenerated, unauthorised access is likely to occur.\n\n### Server actions\n\n`bl` can be used to perform any action that the BinaryLane website can perform,\nincluding:\n\n - Take and restore backups\n - Change plan, operating system, or reinstall\n - Restart and power cycle\n - and many more...\n\nA list of available commands is displayed by running `bl server action`:\n\n```\n$ bl server action\n\nAvailable Commands:\n    add-disk            Create an additional disk for a server\n    attach-backup       Attach a backup to a server\n    change-advanced-features\n                        Change the advanced features of a server\n    change-advanced-firewall-rules\n                        Change the advanced firewall rules for a server\n    change-backup-schedule\n                        Change the backup schedule of a server\n    change-ipv6         Enable or disable IPv6 for a server\n    change-ipv6-reverse-nameservers\n                        Update the IPv6 reverse name servers for a server\n    change-kernel       Change the kernel of a server\n  <additional actions omitted for brevity>\n    ping                Attempt to ping a server\n    power-cycle         Power a server off and then on\n    power-off           Power a server off\n    power-on            Power a server on\n    reboot              Request a server perform a reboot\n    rebuild             Rebuild an existing server\n    rename              Rename a server\n    resize              Update the size and related options for a server\n    resize-disk         Alter the size of an existing disk for a server\n    restore             Restore a backup to a server\n    shutdown            Request a server perform a shutdown\n    take-backup         Take a backup of a server\n    uncancel            Revert the cancellation of a server\n    uptime              Check the uptime of a server\n```\n\nEach server action has a mandatory `SERVER_ID` argument  which can be obtained\nfrom `bl server list`.\n\nMany actions have additional *action-specific* arguments and parameters. Run\n`bl server action COMMAND --help` to see what a particular action supports.\n\n#### Example: password reset\n\n 1. Use `--help` to see the available arguments and parameters:\n\n\n```\n$ bl server action password-reset --help\nusage: bl server action password-reset [OPTIONS] SERVER_ID [PARAMETERS]\n\nReset the Password of a Server\n\n<options omitted for brevity>\n\nArguments:\n  SERVER_ID            The ID of the server on which the action should be performed.\n\nParameters:\n  --username USERNAME  The username of the user to change the password.\n  --password PASSWORD  If this is provided the specified or default remote user\'s account\n                       password will be set to this value.\n```\n\n 2. Use `bl server list` to obtain the numeric server ID. In this example, the\nserver requiring a password reset is ID 123456.\n\n 3. Provide the server ID and desired password to the `password-reset` command:\n\n```\nbl server action password-reset 123456 --password \'qq7s6GYZgbiVG3\'\n```\n\n### Asynchronous actions\n\n`bl` commands that perform an action - `bl create server`, `bl server\naction restore-backup`, and many others - default to *synchronous* handling\nwhere `bl` will display progress information to the console and not exit until\nthe command finishes.\n\nIn some scenarios such as when creating multiple servers, it may be desirable\nrun the command with *asynchronous* handling where `bl` will exit as\nsoon as the BinaryLane API accepts the requested command. To do so, include the\n`--async` option in the command invocation. For example:\n\n```\n$ bl server create --size std-min --image ubuntu-22.04-lts --region syd --async\n```\n\n### Configuration file\n\n`bl configure` creates a configuration file containing the API token, and reads\nthat configuration file on subsequent invocations. The configuration file is\nstored at:\n\n * `$XDG_CONFIG_HOME/binarylane/config.ini`\n\nTypically the environment variable `$XDG_CONFIG_HOME` is not set, in which case\nthe configuration file stored at:\n\n - **Linux/Mac/etc**: `$HOME/.config` - typical file location is\n   `/home/username/.config/binarylane/config.ini`\n - **Windows**: `$APPDATA` - typical file location is\n   `C:\\Users\\UserName\\AppData\\Roaming\\binarylane\\config.ini`\n\n\n### Environment variables\n\nFor environments where the use of `bl configure` and a permanent configuration\nfile are not suitable, environment variables may be utilised instead.\n\nThe environment variable `BL_API_TOKEN` may be used to provide the API token\nrequired to perform `bl` commands.\n\n## Versioning\n\n`bl` uses [semantic versioning](https://semver.org/spec/v2.0.0.html) to version\n[releases](https://github.com/binarylane/binarylane-cli/releases).\n\nSemantic versions are in the form of `MAJOR.MINOR.PATCH`. The value of `MAJOR`\nis currently **0**, which indicates that each new release of the `bl` program may\ncontain changes to its interface that are not backwards-compatible with\nprevious releases such as:\n\n - Command names may change, or moved within the command tree\n - Parameter names may change, or be removed entirely\n - Available field names may change, or be removed entirely\n - Default set of displayed fields displayed in output may change\n\nSuch changes in a new release are not likely to impact interactive use of `bl`,\nbut may cause problems for customers who integrate `bl` into non-interactive\nenvironments such as automation.\n\nIn non-interactive environments, customers should review the release\nChangelog prior to deploying an updated `0.x.y` release, and  ensure that any\nrequired adjustments to the non-interactive environment are made prior to\nupgrading the `bl` program itself.\n',
     'author': "Nathan O'Sullivan",

{binarylane_cli-0.15.0 → binarylane_cli-0.15.1}/src/binarylane/console/runners/command.py

@@ -17,6 +17,9 @@ from binarylane.console.util import create_client
 
 logger = logging.getLogger(__name__)
 
+_DEFAULT_OUTPUT = "table"
+_DEFAULT_HEADER = True
+
 
 class CommandRunner(Runner):
     """CommandRunner parses input, executes API operation and displays the result"""
@@ -25,8 +28,8 @@ class CommandRunner(Runner):
     _client: AuthenticatedClient
 
     _print_curl: Optional[bool]
-    _output: Optional[str] = None
-    _header: Optional[bool] = None
+    _output: str = _DEFAULT_OUTPUT
+    _header: bool = _DEFAULT_HEADER
 
     @abstractmethod
     def create_mapping(self) -> Mapping:
@@ -43,14 +46,14 @@ class CommandRunner(Runner):
             "--no-header",
             dest="runner_header",
             action="store_false",
-            default=True,
+            default=_DEFAULT_HEADER,
             help="Display columns without field labels",
         )
         printers = tuple(item.name.lower() for item in PrinterType)
         parser.add_argument(
             "--output",
             dest="runner_output",
-            default="table",
+            default=_DEFAULT_OUTPUT,
             metavar="OUTPUT",
             choices=printers,
             help='Desired output format [%(choices)s] (default: "%(default)s")',
@@ -73,8 +76,6 @@ class CommandRunner(Runner):
     @property
     def _printer(self) -> Printer:
         """Create printer of requested type"""
-        if self._output is None or self._header is None:
-            raise ValueError(f"output={self._output} header={self._header}")
         printer = create_printer(self._output)
         printer.header = self._header
         return printer
@@ -85,22 +86,24 @@ class CommandRunner(Runner):
 
     def response(self, status_code: int, received: Any) -> None:
         """Format and display response received from API operation"""
+
+        # For successful responses, hand received object to printer
+        if status_code < 300 and received:
+            self._printer.print(received)
+            return
+
+        # For 401 Unauthorized, provide advice on how to resolve
         if status_code == 401:
             self.error(ExitCode.TOKEN, 'Unable to authenticate with API - please run "bl configure" to get started.')
 
-        # No response can be due to a `204 No Content` response, but also when
-        # a response is not documented
+        # If no response is available, report an API error (unless it is `204 No Content`)
         if received is None:
             if status_code != 204:
                 self.error(ExitCode.API, f"HTTP {status_code}")
             return
 
-        # For successful responses, hand received object to printer
-        if status_code < 300:
-            self._printer.print(received)
-
         #
-        # Otherwise, we have received an error response: extract relevant details for display
+        # We have received an error response: extract relevant details for display
         #
 
         # BinaryLane API spec does not currently have correct type on all errors - some are documented as
@@ -128,10 +131,8 @@ class CommandRunner(Runner):
 
     def process(self, parsed: Namespace) -> None:
         self._print_curl = parsed.runner_print_curl
-        if self._output is None:
-            self._output = parsed.runner_output
-        if self._header is None:
-            self._header = parsed.runner_header
+        self._output = parsed.runner_output
+        self._header = parsed.runner_header
 
     def run(self, args: List[str]) -> None:
         # Checks have already been performed during __init__

{binarylane_cli-0.15.0 → binarylane_cli-0.15.1}/src/binarylane/console/runners/list.py

@@ -69,5 +69,3 @@ class ListRunner(CommandRunner):
             self._format = self.default_format[:1]
             self._output = "tsv"
             self._header = False
-
-        super().process(parsed)