Skip to content

Latest commit

 

History

History
137 lines (88 loc) · 4.8 KB

README.md

File metadata and controls

137 lines (88 loc) · 4.8 KB

VMware Carbon Black Cloud Python SDK

This is currently an Alpha Release. Feedback is encouraged.

Latest Version: 1.0.0a1
Release Date: 15 October 2020

Coverage Status Codeship Status for carbonblack/carbon-black-cloud-sdk-python

Recent updates

View the latest release notes here.

License

Use of the Carbon Black Cloud Python SDK is governed by the license found in LICENSE.

Support

  1. View all API and integration offerings on the Developer Network along with reference documentation, video tutorials, and how-to guides.
  2. Use the Developer Community Forum to discuss issues and get answers from other API developers in the Carbon Black Community.
  3. Create a github issue for bugs and change requests. Formal Carbon Black Support coming with v1.0.

Documentation

Visit ReadTheDocs for this project's documentation.

Requirements

The Carbon Black Cloud Python SDK is design to work on Python 3.6 and above.

All requirements are installed as part of pip install carbon-black-cloud-sdk. If you're planning on pushing changes to the Carbon Black Cloud Python SDK, the following can be used after cloning the repo pip install -r requirements.txt

Carbon Black Cloud

At least one Carbon Black Cloud product is required to use this SDK:

Python Packages

  • requests
  • cachetools
  • pyyaml
  • pika
  • prompt_toolkit
  • pygments
  • python-dateutil
  • protobuf
  • solrq
  • validators

If developing the SDK, you also need:

  • pytest==5.4.2
  • pymox==0.7.8
  • coverage==5.1
  • coveralls==2.0.0
  • flake8==3.8.1
  • flake8-colors==0.1.6
  • flake8-docstrings==1.5.0

Getting Started

Visit the Getting Started Guide for an example of authenticating and making an API call using the SDK.

Developing Improvements for the Carbon Black Cloud Python SDK

Use the following steps if you want to provide additional examples, fix a bug, or add a feature to the SDK.

Installing for SDK development

You will need to fork the repo in order to create pull requests when submitting code for review. For details on forking a repo, see here.

git clone https://github.com/{fork-name}/carbon-black-cloud-sdk-python
cd carbon-black-cloud-sdk-python
pip install -r requirements.txt

If you want to test/execute the eample scripts from the repo then install the SDK with the following command. This will install the SDK in editable mode so changes to the repo modify the installed package.

pip install -e .

Note: The above command needs to be run from the base folder of the repo

Running the SDK tests

From the parent directory carbon-black-cloud-sdk-python, run the command pytest.

Building the documentation

ReadTheDocs hosts the documentation for the SDK. If you make changes to the SDK that require an update to the documentation, build the docs locally with the following commands:

sphinx-apidoc -f -o docs src/cbc_sdk
cd docs
make html

The documentation is built in docs/_build/html.

Development Flow

To begin a code change, start by creating a branch off of the develop branch.

git checkout develop
git checkout -b {branch-name}

When the feature or bug fix is finished you will need to create a pull request to the CarbonBlack repo, the following will push your changes to Github.

git push {remote} {branch-name}

If your branch is behind the develop branch, you will need to rebase.

git checkout {branch-name}
git rebase develop

Note: if your develop branch is out of sync with the CarbonBlack repo then you will need to sync your fork. For information on syncing your fork, see here.