mirror of
https://opendev.org/openstack/python-openstackclient.git
synced 2026-01-17 07:20:45 +00:00
Client for OpenStack services
756d2fac67
When the openstackclient in Python2 passes command line arguments to a subcommand it fails to pass the arguments as text (e.g. Unicode). Instead it passes the arguments as binary data encoded using the current locales encoding. An easy way to see this is trying to pass a username with a non-ASCII character. % openstack user delete ñew No user with a name or ID of 'ñew' exists. What occurs internally is when the user data is retrieved it's it properly represented in a Unicode object. However the username pased from the command line is still a str object encoded in the locales encoding (typically UTF-8). A string comparison is attempted between the encoded data from the command line and the Unicode text found in the user representation. This seldom ends well, either the comparison fails to match or a codec error is raised. There is a hard and fast rule, all text data must be stored in Unicode objects and the conversion from binary encoded text to Unicode must occur as close to the I/O boundary as possible. Python3 enforces this behavior automatically but in Python2 it is the programmers job to do so. In the past there have been attempts to fix problems deep inside internal code by attempting to decode from UTF-8. There are two problems with this approach. First, internal code has no way to accurately know what encoding was used to encode the binary data. This is way it needs to be decoded as close to the I/O source as possible because that is the best place to know the actual encoding. Guessing UTF-8 is at best a heuristic. Second, there must be a canonical representation for data "inside" the program, you don't want dozens of individual modules, classes, methods, etc. performing conversions, instead they should be able to make the assumption in what format text is represented in, the format for text data must be Unicode. This is another reason to decode as close to the I/O as possible. In Python3 the argv strings are decoded from the locales encoding by the interpreter. By the time any Python3 code sees the argv strings they will be Unicode. However in Python2 there must be explicit code added to decode the argv strings into Unicode. The conversion of sys.argv into Unicode only occurs when argv is not passed to OpenStackShell.run(). If a caller of OpenStackShell.run() supplies their own arg it is their responsiblity to assure they are passing actual text objects. Consider this a requirement of the API. Note: This patch does not contain a unittest to exercise the behavior because it is difficult to construct a test that depends on command invocation from a shell. The general structure of the unit tests is to pass fake argv into OpenStackShell.run() as if it came from a shell. Because the new code only operates when argv is not passed and defaults to sys.argv it conflicts with the unittest design. Change-Id: I779d260744728eae8455ff9dedb6e5c09c165559 Closes-Bug: 1603494 Signed-off-by: John Dennis <jdennis@redhat.com> |
||
|---|---|---|
| doc | ||
| examples | ||
| functional | ||
| openstackclient | ||
| releasenotes | ||
| tools | ||
| .coveragerc | ||
| .gitignore | ||
| .gitreview | ||
| .mailmap | ||
| .testr.conf | ||
| babel.cfg | ||
| CONTRIBUTING.rst | ||
| HACKING.rst | ||
| LICENSE | ||
| post_test_hook.sh | ||
| README.rst | ||
| requirements.txt | ||
| setup.cfg | ||
| setup.py | ||
| test-requirements.txt | ||
| tox.ini | ||
===============
OpenStackClient
===============
.. image:: https://img.shields.io/pypi/v/python-openstackclient.svg
:target: https://pypi.python.org/pypi/python-openstackclient/
:alt: Latest Version
.. image:: https://img.shields.io/pypi/dm/python-openstackclient.svg
:target: https://pypi.python.org/pypi/python-openstackclient/
:alt: Downloads
OpenStackClient (aka OSC) is a command-line client for OpenStack that brings
the command set for Compute, Identity, Image, Object Store and Block Storage
APIs together in a single shell with a uniform command structure.
The primary goal is to provide a unified shell command structure and a common
language to describe operations in OpenStack.
* `PyPi`_ - package installation
* `Online Documentation`_
* `Launchpad project`_ - release management
* `Blueprints`_ - feature specifications
* `Bugs`_ - issue tracking
* `Source`_
* `Developer` - getting started as a developer
* `Contributing` - contributing code
* `Testing` - testing code
* IRC: #openstack-sdks on Freenode (irc.freenode.net)
* License: Apache 2.0
.. _PyPi: https://pypi.python.org/pypi/python-openstackclient
.. _Online Documentation: http://docs.openstack.org/developer/python-openstackclient/
.. _Launchpad project: https://launchpad.net/python-openstackclient
.. _Blueprints: https://blueprints.launchpad.net/python-openstackclient
.. _Bugs: https://bugs.launchpad.net/python-openstackclient
.. _Source: https://git.openstack.org/cgit/openstack/python-openstackclient
.. _Developer: http://docs.openstack.org/project-team-guide/project-setup/python.html
.. _Contributing: http://docs.openstack.org/infra/manual/developers.html
.. _Testing: http://docs.openstack.org/developer/python-openstackclient/developing.html#testing
Getting Started
===============
OpenStack Client can be installed from PyPI using pip::
pip install python-openstackclient
There are a few variants on getting help. A list of global options and supported
commands is shown with ``--help``::
openstack --help
There is also a ``help`` command that can be used to get help text for a specific
command::
openstack help
openstack help server create
If you want to make changes to the OpenStackClient for testing and contribution,
make any changes and then run::
python setup.py develop
or::
pip install -e .
Configuration
=============
The CLI is configured via environment variables and command-line
options as listed in http://docs.openstack.org/developer/python-openstackclient/authentication.html.
Authentication using username/password is most commonly used::
export OS_AUTH_URL=<url-to-openstack-identity>
export OS_PROJECT_NAME=<project-name>
export OS_USERNAME=<username>
export OS_PASSWORD=<password> # (optional)
The corresponding command-line options look very similar::
--os-auth-url <url>
--os-project-name <project-name>
--os-username <username>
[--os-password <password>]
If a password is not provided above (in plaintext), you will be interactively
prompted to provide one securely.
Authentication may also be performed using an already-acquired token
and a URL pointing directly to the service API that presumably was acquired
from the Service Catalog::
export OS_TOKEN=<token>
export OS_URL=<url-to-openstack-service>
The corresponding command-line options look very similar::
--os-token <token>
--os-url <url-to-openstack-service>