Skip to main content
"stackql logo"

PyStackQL - Python Wrapper for StackQL

Documentation Status PyPI PyPI - Downloads

StackQL is an open source developer tool which allows you to query and interact with cloud and SaaS provider APIs using SQL grammar. StackQL can be used for cloud inventory analysis, cloud cost optimization, cloud security and compliance, provisioning/IaC, assurance, XOps, and more.

PyStackQL is a Python wrapper for StackQL which allows you to use StackQL within Python applications and to use the power of Python to extend StackQL. PyStackQL can be used with pandas, matplotlib, plotly, jupyter and other Python libraries to create powerful data analysis and visualization applications.

For detailed documentation, including the API reference, see Read the Docs.

Installing PyStackQL

PyStackQL can be installed with pip as follows:

pip install pystackql

You can install from source by cloning this repository and running a pip install command in the root directory of the repository:

git clone https://github.com/stackql/pystackql
cd pystackql
pip install .

Using PyStackQL

The following example demonstrates how to run a query and return the results as a pandas.DataFrame:

from pystackql import StackQL
region = "ap-southeast-2"
stackql = StackQL(output='pandas')

query = """
SELECT instance_type, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region = '%s'
GROUP BY instance_type
""" % (region)

df = stackql.execute(query)
print(df)

Using PyStackQL with Jupyter Notebook

To use the integrated Jupyter magic commands provided by PyStackQL:

  1. Load the Extension:

%load_ext pystackql.magic
  1. Execute a Query Using Line Magic:

%stackql SHOW SERVICES IN azure
  1. Or Using Cell Magic:

%%stackql
SELECT status, count(*) as num_instances
FROM google.compute.instances
WHERE project = '$project'
AND zone = '$zone'
GROUP BY status

You can find more examples in the stackql docs or the examples in readthedocs.

Supported Operating Systems

PyStackQL (and StackQL) are supported on:

  • MacOS (arm and amd)

  • Linux

  • Windows

Supported Python Versions

PyStackQL has been tested on:

  • Python 3.9

  • Python 3.10

  • Python 3.11

  • Python 3.12

  • Python 3.13

Licensing

PyStackQL is licensed under the MIT License. The license is available here

Building the docs

To build the docs, you will need to install the following packages:

pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints

Then, from the root directory of the repository, run:

cd docs
make html

The docs will be built in the docs/build/html directory.

Building the package

To build the package, you will need to install the following packages:

pip install build twine

Then, from the root directory of the repository, run:

rm -rf dist/*
python3 -m build

The package will be built in the dist directory.

Testing Locally

Before testing, ensure you have all the required packages installed:

pip install -r requirements.txt
pip install psycopg

Once the dependencies are installed, you can run the tests using the provided script:

sh run_tests

This script sets up the necessary environment variables and then runs the unit tests.

Note: Make sure to set up the environment variables in the tests/creds/env_vars/test.env file or supply them in another way before running the tests. The tests may require specific configurations or access keys to connect to services.

For better isolation and reproducibility, consider using a virtual environment:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Once you’re done testing, you can deactivate the virtual environment:

deactivate

Publishing the package

To publish the package to PyPI, run the following command:

twine upload --config-file .pypirc dist/*

Metadata

Release files for pystackql 3.8.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pystackql 3.8.5
File Size Uploaded Provenance Actions
pystackql-3.8.5.tar.gz 49.4 kB Without provenance Details for pystackql-3.8.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pystackql 3.8.5
File Interpreter ABI Platform Actions
pystackql-3.8.5-py3-none-any.whl Python 3 none any Details for pystackql-3.8.5-py3-none-any.whl

Total release size: 84.0 kB

Release files / pystackql-3.8.5.tar.gz

Download URL pystackql-3.8.5.tar.gz
Size 49.4 kB
Tags Source
SHA-256 checksum
How to use checksums
c351c61bcf66b051a5e3f4d0a620ef6b10cc9f5ef4b916030f654bdf43a16457
BLAKE2b-256 checksum
How to use checksums
8e204f928db1d4a5beca04e52e67578d3c78730daf5ca5948db8bd877bec0856
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / pystackql-3.8.5-py3-none-any.whl

Download URL pystackql-3.8.5-py3-none-any.whl
Size 34.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ccb9e422a7e4b26f972117d3570163c9516dc150e81bd4f78c9f608dcaf7b157
BLAKE2b-256 checksum
How to use checksums
3a2ac2e090aaf40c0acca2734b005a3db6767e69a49ea52397ff1df5c2dea9b5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for pystackql 3.8.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.8.5 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page