DOCSEARCHbyAlgolia
Submit Docs

pyvcloud Python SDK

repository·master·Indexed 41 days ago

https://github.com/vmware-archive/pyvcloud

Python SDK for VMware vCloud Director, supporting API versions 29.0 through 36.0. It serves as the underlying library for the vcd-cli tool.

Tokens
10.3K
Snippets
33
Records
48
Agent score
51%

What's inside pyvcloud

  1. Explore the pyvcloud package structure

    master

    The pyvcloud package is organized into two primary subpackages:

    • pyvcloud.vcd: Likely contains the core client logic and API interactions for VMware Cloud Director.
    • pyvcloud.system_test_framework: Contains tools and frameworks for performing system-level testing.

    Users should look into pyvcloud.vcd for general API usage and pyvcloud.system_test_framework for automation and testing workflows.

  2. Overview of the pyvcloud.vcd package submodules

    master

    The pyvcloud.vcd package is the core module for interacting with VMware Cloud Director (VCD). It is organized into several submodules that categorize different aspects of the VCD environment and API interactions. Key functional areas include:

    • Core Infrastructure: client (for API connections), platform, system, and org (for organizational structures).
    • Resource Management: vdc (Virtual Data Centers), vapp (vApps), vm (Virtual Machines), and pvdc (Private Cloud).
    • Access & Security: acl (Access Control Lists) and role (User Roles).
    • Operations & Communication: task (for monitoring asynchronous operations), amqp (for messaging), and api_extension / extension (for extending API functionality).
    • Utilities & Error Handling: utils, exceptions, and test.

  3. Understand the pyvcloud exception hierarchy

    master

    All exceptions in pyvcloud inherit from SDKException. This base class is split into two primary branches depending on the source of the error:

    1. VcdException: Errors originating from the VCD server. These may be caused by error response codes or the state of VCD entities. Retrying an operation after resolving the underlying VCD issue may succeed.
    2. ClientException: Errors originating within the pyvcloud client itself. Retrying these operations without code or configuration changes will not work.

    Use this distinction to decide whether your error handling logic should implement a retry mechanism (for VcdException) or treat the error as a fatal client-side issue (for ClientException).

  4. Install pyvcloud from local source (Development Mode)

    master

    For development, clone the repository and use setup.py develop. This allows scripts to automatically pick up changes made to the source code. It is highly recommended to do this within a virtualenv.

    $ git clone https://github.com/vmware/pyvcloud.git
$ cd pyvcloud
$ python3 setup.py develop

  5. Install pyvcloud

    master

    You can install pyvcloud using pip. Depending on your operating system and distribution, you may need to install additional system packages to ensure a successful installation. Refer to docs/install.md for platform-specific details.

    $ pip install --user pyvcloud

  6. Run pyvcloud system tests

    master

    System tests exercise pyvcloud API functions and can be run either individually using unittest or as a batch using the provided shell script.

    Running individual tests

    1. Fill in the required values in base_config.yaml.
    2. Execute the test file using the Python unittest module:
      python3 -m unittest <test_file_name>.py

    Running tests in a build environment

    1. Copy ../examples/vcd_connection.sample to a file named vcd_connection and populate it with your connection data.
    2. Export the path to this file using the VCD_CONNECTION environment variable:
      export VCD_CONNECTION=$PWD/vcd_connection
    3. Execute the test runner script:
      ./run_system_tests.sh
      You can pass specific test filenames as arguments to run a subset of tests: ./run_system_tests.sh my_test.py.
    python3 -m unittest idisk_tests.py

# Or for builds:
export VCD_CONNECTION=$PWD/vcd_connection
./run_system_tests.sh my_test.py

  7. How to write new pyvcloud system tests

    master

    System tests extend the Python unittest framework and utilize a custom BaseTestCase class (found in pyvcloud.system_test_framework). BaseTestCase uses an Environment class to automatically manage fixtures like test orgs, users, or VDCs.

    Development Workflow

    1. Template: Copy an existing test file to a new name (e.g., my_test.py).
    2. Implementation: Add test cases. Tests are typically written to be order-dependent to share complex state.
      • Naming: Use numeric prefixes to enforce run order (e.g., test_0030_get_disk_by_id).
      • Documentation: Include a docstring summarizing the verification.
      • Helpers: Prefix private helper methods with an underscore (e.g., _setup_stuff).
    3. Setup/Teardown: Use specialized test cases for state management:
      • test_0000_setup: Create custom state.
      • test_9999_teardown: Remove custom state.
      • Use the @developerModeAware decorator on teardown methods to prevent them from running when developer mode is enabled in base_config.yaml. This leaves the environment state intact for debugging.
    4. Environment Access: Use Environment class methods to retrieve required objects. For example, to get an Org admin client:
      org_admin_client = Environment.get_client_in_default_org(CommonRoles.ORGANIZATION_ADMINISTRATOR)
      You can also access configuration values directly via Environment._config.
    5. Configuration: Update base_config.yaml with vCD host and credentials.
    6. Execution: Run via ./run_system_tests.sh or via unittest.
    7. Linting: Run flake8 before checking in code.
    @developerModeAware
def test_9999_teardown(self):
    """Remove stuff, etc."""

org_admin_client = Environment.get_client_in_default_org(
    CommonRoles.ORGANIZATION_ADMINISTRATOR)

vcd_host = Environment._config['vcd']['host']

  8. Install pyvcloud on Mac OS X

    master

    On macOS, you must first install the Xcode Command Line Tools. Then, install pip using easy_install and finally install pyvcloud using pip3.

    Troubleshooting Mac SSL/Path issues:

    • If experiencing path or SSL issues with newer Python versions (e.g., 3.6.4), ensure your PATH points to the specific Python framework bin directory and upgrade pbr.
    • If experiencing SSL errors with older Python 3 versions, install urllib3 and pyopenssl.
    # Install Xcode Command Line Tools
$ xcode-select --install

# Install pip3
$ sudo easy_install pip

# Install pyvcloud
$ pip3 install --user pyvcloud

# Fix for path/SSL issues (example for Python 3.6)
$ export PATH=/Library/Frameworks/Python.framework/Versions/3.6/bin:$PATH
$ pip3 install --user pbr

# Fix for older OpenSSL issues
$ pip3 install --user urllib3 pyopenssl

  9. Run pyvcloud scripts using an existing virtualenv

    master

    If you already have a virtual environment activated, you can skip the installation script and run tox, examples, and system tests directly. Ensure VCD_CONNECTION is exported.

    . .venv/bin/activate

./support/tox.sh

export VCD_CONNECTION=/path/to/vcd_connection
./examples/run_examples.sh
./system_tests/run_system_tests.sh

  10. Set up a Sphinx documentation project

    master

    To initialize a Sphinx project within the docs directory, use sphinx-quickstart.

    pip3 install Sphinx
cd docs
sphinx-quickstart

    Recommended options during setup:

    • Split source and build directories in the root path: y
    • Automatically insert Python module docstrings: y
    • Create .nojekyll file on built HTML: y (This ensures GitHub Pages doesn't use Jekyll, which can interfere with Sphinx output).

  11. Build and publish documentation for pyvcloud

    master

    Pyvcloud uses Sphinx to generate documentation from Python docstrings and publishes it to GitHub Pages via the gh-pages branch. The build process involves generating HTML in the local docs directory and then syncing those files to a separate documentation clone repository.

    1. Prepare the documentation clone (One-time setup)

    Clone the repository into a separate directory to act as your documentation host and set the PYVCLOUD_DOCS environment variable.

    git clone git@github.com:vmware/pyvcloud.git pyvcloud-docs
export PYVCLOUD_DOCS=$PWD/pyvcloud-docs

    2. Generate and sync documentation

    Run these commands from the docs directory of your main repository:

    pip3 install -r doc-requirements.txt  # Ensure Sphinx is installed
sphinx-apidoc -f --separate -o source ../pyvcloud
make html
rsync -avr build/html/ $PYVCLOUD_DOCS

    Note: -f overwrites previous files and --separate generates separate pages.

    3. Push to GitHub

    Commit the changes in the documentation clone and push to the gh-pages branch:

    cd $PYVCLOUD_DOCS
git add .
git commit -m "Documentation build"
git push origin gh-pages
    pip3 install -r doc-requirements.txt
sphinx-apidoc -f --separate -o source ../pyvcloud
make html
rsync -avr build/html/ $PYVCLOUD_DOCS

  12. Install pyvcloud using virtualenv

    master

    Using a virtual environment is recommended to avoid polluting your system Python installation. When using venv, do not use the --user flag, as the virtual environment manages its own package locations.

    $ python3 -m venv $HOME/my_venv
$ . $HOME/my_venv/bin/activate
(my_venv) $ pip3 install pyvcloud
# To exit
(my_venv) $ deactivate