{"id":21262847,"url":"https://github.com/stackql/pystackql","last_synced_at":"2025-07-11T04:31:14.736Z","repository":{"id":72459794,"uuid":"455730530","full_name":"stackql/pystackql","owner":"stackql","description":"Python interface for StackQL","archived":false,"fork":false,"pushed_at":"2024-11-19T02:52:44.000Z","size":7784,"stargazers_count":9,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-11-19T03:10:04.417Z","etag":null,"topics":["analytics","cloud","cspm","infrastructure-as-code","pypi","pystackql","python","saas","sql","stackql"],"latest_commit_sha":null,"homepage":"https://pystackql.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stackql.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-04T23:51:14.000Z","updated_at":"2024-11-19T02:52:48.000Z","dependencies_parsed_at":"2024-11-08T00:30:44.237Z","dependency_job_id":null,"html_url":"https://github.com/stackql/pystackql","commit_stats":{"total_commits":38,"total_committers":3,"mean_commits":"12.666666666666666","dds":"0.21052631578947367","last_synced_commit":"605b174bed9de2795a05e9bdde5cdfd286a5be62"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fpystackql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fpystackql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fpystackql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stackql%2Fpystackql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stackql","download_url":"https://codeload.github.com/stackql/pystackql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225674897,"owners_count":17506272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","cloud","cspm","infrastructure-as-code","pypi","pystackql","python","saas","sql","stackql"],"created_at":"2024-11-21T04:59:31.255Z","updated_at":"2025-07-11T04:31:14.718Z","avatar_url":"https://github.com/stackql.png","language":"Python","readme":".. image:: https://stackql.io/img/stackql-logo-bold.png\r\n    :alt: \"stackql logo\"\r\n    :target: https://github.com/stackql/stackql\r\n    :align: center\r\n\r\n======================================\r\nPyStackQL - Python Wrapper for StackQL\r\n======================================\r\n\r\n.. image:: https://readthedocs.org/projects/pystackql/badge/?version=latest\r\n   :target: https://pystackql.readthedocs.io/en/latest/\r\n   :alt: Documentation Status\r\n\r\n.. image:: https://img.shields.io/pypi/v/pystackql\r\n   :target: https://pypi.org/project/pystackql/\r\n   :alt: PyPI\r\n\r\n.. image:: https://img.shields.io/pypi/dm/pystackql?label=pypi%20downloads\r\n   :target: https://pypi.org/project/pystackql/\r\n   :alt: PyPI - Downloads\r\n\r\nStackQL is an open source developer tool which allows you to query and interact with cloud and SaaS provider APIs using SQL grammar.\r\nStackQL can be used for cloud inventory analysis, cloud cost optimization, cloud security and compliance, provisioning/IaC, assurance, XOps, and more.\r\n\r\n`PyStackQL \u003chttps://pypi.org/project/pystackql/\u003e`_ 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.  \r\nPyStackQL can be used with ``pandas``, ``matplotlib``, ``plotly``, ``jupyter`` and other Python libraries to create powerful data analysis and visualization applications.\r\n\r\nFor detailed documentation, including the API reference, see `Read the Docs \u003chttps://pystackql.readthedocs.io\u003e`_.\r\n\r\nInstalling PyStackQL\r\n--------------------\r\n\r\nPyStackQL can be installed with pip as follows:\r\n\r\n::\r\n\r\n    pip install pystackql\r\n\r\nYou can install from source by cloning this repository and running a pip install command in the root directory of the repository:\r\n\r\n::\r\n\r\n    git clone https://github.com/stackql/pystackql\r\n    cd pystackql\r\n    pip install .\r\n\r\nUsing PyStackQL\r\n---------------\r\n\r\nThe following example demonstrates how to run a query and return the results as a ``pandas.DataFrame``:\r\n\r\n::\r\n\r\n    from pystackql import StackQL\r\n    region = \"ap-southeast-2\"\r\n    stackql = StackQL(output='pandas')\r\n    \r\n    query = \"\"\"\r\n    SELECT instance_type, COUNT(*) as num_instances\r\n    FROM aws.ec2.instances\r\n    WHERE region = '%s'\r\n    GROUP BY instance_type\r\n    \"\"\" % (region)   \r\n    \r\n    df = stackql.execute(query)\r\n    print(df)\r\n\r\nUsing PyStackQL with Jupyter Notebook\r\n-------------------------------------\r\n\r\nTo use the integrated Jupyter magic commands provided by PyStackQL:\r\n\r\n1. **Load the Extension**:\r\n\r\n.. code-block:: python\r\n\r\n    %load_ext pystackql.magic\r\n\r\n2. **Execute a Query Using Line Magic**:\r\n\r\n.. code-block:: python\r\n\r\n    %stackql SHOW SERVICES IN azure\r\n\r\n3. **Or Using Cell Magic**:\r\n\r\n.. code-block:: python\r\n\r\n    %%stackql\r\n    SELECT status, count(*) as num_instances\r\n    FROM google.compute.instances\r\n    WHERE project = '$project' \r\n    AND zone = '$zone'\r\n    GROUP BY status\r\n\r\nYou can find more examples in the `stackql docs \u003chttps://stackql.io/docs\u003e`_ or the examples in `readthedocs \u003chttps://pystackql.readthedocs.io/en/latest/examples.html\u003e`_.\r\n\r\nSupported Operating Systems\r\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nPyStackQL (and StackQL) are supported on:\r\n\r\n- MacOS (arm and amd)\r\n- Linux\r\n- Windows\r\n\r\nSupported Python Versions\r\n~~~~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nPyStackQL has been tested on:\r\n\r\n- Python 3.9\r\n- Python 3.10\r\n- Python 3.11\r\n- Python 3.12\r\n- Python 3.13\r\n\r\nLicensing\r\n~~~~~~~~~\r\nPyStackQL is licensed under the MIT License. The license is available `here \u003chttps://github.com/stackql/pystackql/blob/main/LICENSE\u003e`_\r\n\r\nBuilding the docs\r\n~~~~~~~~~~~~~~~~~\r\n\r\nTo build the docs, you will need to install the following packages:\r\n\r\n::\r\n\r\n    pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints\r\n\r\nThen, from the root directory of the repository, run:\r\n\r\n::\r\n\r\n    cd docs\r\n    make html\r\n\r\nThe docs will be built in the ``docs/build/html`` directory.\r\n\r\nBuilding the package\r\n~~~~~~~~~~~~~~~~~~~~\r\n\r\nTo build the package, you will need to install the following packages:\r\n\r\n::\r\n\r\n    pip install build\r\n\r\nThen, from the root directory of the repository, run:\r\n\r\n::\r\n\r\n    rm -rf dist/*\r\n    python3 -m build    \r\n\r\nThe package will be built in the ``dist`` directory.\r\n\r\nTesting Locally\r\n---------------\r\n\r\nBefore testing, ensure you have all the required packages installed:\r\n\r\n::\r\n\r\n    pip install -r requirements.txt\r\n    pip install psycopg\r\n\r\nOnce the dependencies are installed, you can run the tests using the provided script:\r\n\r\n::\r\n\r\n    sh run_tests\r\n\r\nThis script sets up the necessary environment variables and then runs the unit tests.\r\n\r\nNote: 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.\r\n\r\nFor better isolation and reproducibility, consider using a virtual environment:\r\n\r\n::\r\n\r\n    python3 -m venv venv\r\n    source venv/bin/activate\r\n    pip install -r requirements.txt\r\n\r\nOnce you're done testing, you can deactivate the virtual environment:\r\n\r\n::\r\n\r\n    deactivate\r\n\r\nPublishing the package\r\n~~~~~~~~~~~~~~~~~~~~~~\r\n\r\nTo publish the package to PyPI, run the following command:\r\n\r\n::\r\n\r\n    twine upload --config-file .pypirc dist/*\r\n\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fpystackql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackql%2Fpystackql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackql%2Fpystackql/lists"}