| Name | civis JSON |
| Version |
2.4.3
JSON |
| download |
| home_page | None |
| Summary | Civis API Python Client |
| upload_time | 2025-01-13 19:09:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | BSD-3-Clause |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Civis API Python Client
=======================
.. start-include-marker-introductory-paragraph
|PyPI| |PyVersions| |CircleCI| |Documentation|
.. |CircleCI| image:: https://circleci.com/gh/civisanalytics/civis-python.svg?style=shield
:target: https://circleci.com/gh/civisanalytics/civis-python
:alt: CircleCI build status
.. |PyPI| image:: https://img.shields.io/pypi/v/civis.svg
:target: https://pypi.org/project/civis/
:alt: Latest version on PyPI
.. |PyVersions| image:: https://img.shields.io/pypi/pyversions/civis.svg
:target: https://pypi.org/project/civis/
:alt: Supported python versions for civis-python
.. |Documentation| image:: https://readthedocs.org/projects/civis-python/badge/?version=latest
:target: https://civis-python.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
The Civis API Python client is a Python package that helps analysts
and developers interact with Civis Platform programmatically. The package includes a set of
tools around common workflows as well as a convenient interface to make
requests directly to the Civis API.
.. end-include-marker-introductory-paragraph
Please see the
`full documentation <https://civis-python.readthedocs.io>`_ for more details.
.. start-include-marker-api-keys-section
API Keys
--------
In order to make requests to the Civis API,
you will need a Civis Platform API key that is unique to you.
Instructions for creating a new key are found
`here <https://civis.zendesk.com/hc/en-us/articles/216341583-Generating-an-API-Key>`_.
API keys have a set expiration date and new keys will need to be created at
least every 30 days. The API client will look for a ``CIVIS_API_KEY``
environment variable to access your API key, so after creating a new API key,
follow the steps below for your operating system to set up your environment.
Linux / MacOS
~~~~~~~~~~~~~
1. Add the following to your shell configuration file (``~/.zshrc`` for MacOS or ``~/.bashrc`` for Linux, by default)::
export CIVIS_API_KEY="alphaNumericApiK3y"
2. Source your shell configuration file (or restart your terminal).
Windows
~~~~~~~
1. Navigate to "Settings" -> type "environment" in search bar ->
"Edit environment variables for your account". This can also be found
in "System Properties" -> "Advanced" -> "Environment Variables...".
2. In the user variables section, if ``CIVIS_API_KEY`` already exists in
the list of environment variables, click on it and press "Edit...".
Otherwise, click "New..".
3. Enter CIVIS_API_KEY as the "Variable name".
4. Enter your API key as the "Variable value". Your API key should look
like a long string of letters and numbers.
.. end-include-marker-api-keys-section
.. start-include-marker-installation-section
Installation
------------
After creating an API key and setting the ``CIVIS_API_KEY`` environment
variable, install the Python package ``civis`` with the recommended method via ``pip``::
pip install civis
Alternatively, if you are interested in the latest functionality not yet released through ``pip``,
you may clone the code from GitHub and build from source (``git`` assumed to be available):
.. code-block:: bash
pip install git+https://github.com/civisanalytics/civis-python.git
You can test your installation by running
.. code-block:: python
import civis
client = civis.APIClient()
print(client.users.list_me()['username'])
If ``civis`` was installed correctly, this will print your Civis
Platform username.
The client has a soft dependency on ``pandas`` to support features such as
data type parsing. If you are using the ``io`` namespace to read or write
data from Civis, it is highly recommended that you install ``pandas`` and
set ``use_pandas=True`` in functions that accept that parameter. To install
``pandas``:
.. code-block:: bash
pip install pandas
Machine learning features in the ``ml`` namespace have a soft dependency on
``scikit-learn`` and ``pandas``. Install ``scikit-learn`` to
export your trained models from the Civis Platform or to
provide your own custom models. Use ``pandas`` to download model predictions
from the Civis Platform. The ``civis.ml`` code
optionally uses the `feather <https://github.com/wesm/feather>`_
format to transfer data from your local computer to Civis
Platform. Install these dependencies with
.. code-block:: bash
pip install scikit-learn
pip install pandas
pip install feather-format
Some CivisML models have open-source dependencies in
addition to ``scikit-learn``, which you may need if you want to
download the model object. These dependencies are
``civisml-extensions``, ``glmnet``, and ``muffnn``. Install these
dependencies with
.. code-block:: bash
pip install civisml-extensions
pip install glmnet
pip install muffnn
.. end-include-marker-installation-section
Usage
-----
``civis`` includes a number of wrappers around the Civis API for
common workflows.
.. code-block:: python
import civis
df = civis.io.read_civis(table="my_schema.my_table",
database="database",
use_pandas=True)
The Civis API may also be directly accessed via the ``APIClient`` class.
.. code-block:: python
import civis
client = civis.APIClient()
database = client.databases.list()
See the `documentation <https://civis-python.readthedocs.io>`_ for a more
complete user guide.
Building Documentation
----------------------
Background:
* We use the Sphinx framework. The documentation source files are in ``docs/``.
* All auto-generated files, including the HTML pages, are explicitly not versioned
(see ``.gitignore``).
For the public documentation at https://civis-python.readthedocs.io:
* The doc build is configured by ``.readthedocs.yaml``.
Normally, even when we need to update the documentation or make a new release of civis-python,
neither this configuration YAML file nor Civis's account on the Read the Docs site need
any updates.
* To update the documentation, the files under ``docs/`` can be updated as needed.
If the "API Resources" pages need to be updated because the upstream Civis API has been updated,
then the following need to happen:
(i) the new Civis API updates must be accessible by a "standard" Civis Platform user,
i.e., not behind a feature flag, and
(ii) you'll need to locally run ``python tools/update_civis_api_spec.py`` to update
``civis_api_spec.json`` inside the ``civis`` Python package codebase.
It is this JSON file that's the basis for the Civis API information on the "API Resources" pages.
Regardless of which Civis API key you use to run ``python tools/update_civis_api_spec.py``,
the updated ``civis_api_spec.json`` only contains Civis API information available to
a standard Civis Platform user.
* The URL https://civis-python.readthedocs.io auto-redirects to
the "stable" URL https://civis-python.readthedocs.io/en/stable/ which reflects
the most recent released civis-python version
(every GitHub release with the tag "vX.Y.Z" triggers a new "stable" doc build
on the Read The Docs site).
In contrast, the "latest" URL https://civis-python.readthedocs.io/en/latest/ reflects
the most recent commit to the upstream ``main`` branch of the civis-python codebase on GitHub.
If there are doc changes (e.g., new or removed Civis API methods) that we'd really like to
show up at the "stable" URL sooner rather than waiting for the next release with other code changes,
we can make a patch release (i.e., increment the "Z" in "vX.Y.Z").
The doc build has its full dependencies listed in ``docs/requirements.txt``.
To update this file:
* Install the latest version of ``pip-tools``: ``pip install --upgrade pip-tools``.
* Run the ``pip-compile`` command at the top of ``docs/requirements.txt``, with the flag
``--upgrade`` added to upgrade all transitive dependencies as well.
To build the documentation locally, for testing and development:
* Install the full doc-related dependencies: ``pip install -r docs/requirements.txt``.
* Run ``sphinx-build -b html docs docs/build``.
In case you would like for the "API Resources" page to locally show what a specific
Civis Platform user would see from the Civis API
(rather than use the available ``civis_api_spec.json`` for a standard Civis Platform user),
set the environment variable ``CIVIS_API_KEY`` to this user's key
and prepend this command with ``FETCH_REMOTE_RESOURCES=true``.
Command-line Interface (CLI)
----------------------------
After installing the Python package, you'll also have a ``civis`` command accessible from your shell. It surfaces a commandline interface to all of the regular Civis API endpoints, plus a few helpers. To get started, run ``civis --help``.
Please see the `CLI documentation <https://civis-python.readthedocs.io/en/stable/cli.html>`_ for more details.
Contributing
------------
See `CONTRIBUTING.md <CONTRIBUTING.md>`_ for information about contributing to this project.
License
-------
BSD-3
See `LICENSE.md <LICENSE.md>`_ for details.
For Maintainers
---------------
The `tools <tools/>`_ directory contains scripts that civis-python maintainers can
use (and maintain...). Please see their docstrings for usage.
Non-public information can be found by searching the internal documentation system
or consulting the current maintainers.
Raw data
{
"_id": null,
"home_page": null,
"name": "civis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Civis Analytics <opensource@civisanalytics.com>",
"download_url": "https://files.pythonhosted.org/packages/41/03/d91ab9c400ee6741bbcc0a2e6ae7b78ec160f40471e9a2527366563b8eae/civis-2.4.3.tar.gz",
"platform": null,
"description": "Civis API Python Client\n=======================\n\n.. start-include-marker-introductory-paragraph\n\n|PyPI| |PyVersions| |CircleCI| |Documentation|\n\n.. |CircleCI| image:: https://circleci.com/gh/civisanalytics/civis-python.svg?style=shield\n :target: https://circleci.com/gh/civisanalytics/civis-python\n :alt: CircleCI build status\n\n.. |PyPI| image:: https://img.shields.io/pypi/v/civis.svg\n :target: https://pypi.org/project/civis/\n :alt: Latest version on PyPI\n\n.. |PyVersions| image:: https://img.shields.io/pypi/pyversions/civis.svg\n :target: https://pypi.org/project/civis/\n :alt: Supported python versions for civis-python\n\n.. |Documentation| image:: https://readthedocs.org/projects/civis-python/badge/?version=latest\n :target: https://civis-python.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\nThe Civis API Python client is a Python package that helps analysts\nand developers interact with Civis Platform programmatically. The package includes a set of\ntools around common workflows as well as a convenient interface to make\nrequests directly to the Civis API.\n\n.. end-include-marker-introductory-paragraph\n\nPlease see the\n`full documentation <https://civis-python.readthedocs.io>`_ for more details.\n\n.. start-include-marker-api-keys-section\n\nAPI Keys\n--------\n\nIn order to make requests to the Civis API,\nyou will need a Civis Platform API key that is unique to you.\nInstructions for creating a new key are found\n`here <https://civis.zendesk.com/hc/en-us/articles/216341583-Generating-an-API-Key>`_.\nAPI keys have a set expiration date and new keys will need to be created at\nleast every 30 days. The API client will look for a ``CIVIS_API_KEY``\nenvironment variable to access your API key, so after creating a new API key,\nfollow the steps below for your operating system to set up your environment.\n\nLinux / MacOS\n~~~~~~~~~~~~~\n\n1. Add the following to your shell configuration file (``~/.zshrc`` for MacOS or ``~/.bashrc`` for Linux, by default)::\n\n export CIVIS_API_KEY=\"alphaNumericApiK3y\"\n\n2. Source your shell configuration file (or restart your terminal).\n\nWindows\n~~~~~~~\n\n1. Navigate to \"Settings\" -> type \"environment\" in search bar ->\n \"Edit environment variables for your account\". This can also be found\n in \"System Properties\" -> \"Advanced\" -> \"Environment Variables...\".\n2. In the user variables section, if ``CIVIS_API_KEY`` already exists in\n the list of environment variables, click on it and press \"Edit...\".\n Otherwise, click \"New..\".\n3. Enter CIVIS_API_KEY as the \"Variable name\".\n4. Enter your API key as the \"Variable value\". Your API key should look\n like a long string of letters and numbers.\n\n.. end-include-marker-api-keys-section\n\n.. start-include-marker-installation-section\n\nInstallation\n------------\n\nAfter creating an API key and setting the ``CIVIS_API_KEY`` environment\nvariable, install the Python package ``civis`` with the recommended method via ``pip``::\n\n pip install civis\n\nAlternatively, if you are interested in the latest functionality not yet released through ``pip``,\nyou may clone the code from GitHub and build from source (``git`` assumed to be available):\n\n.. code-block:: bash\n\n pip install git+https://github.com/civisanalytics/civis-python.git\n\nYou can test your installation by running\n\n.. code-block:: python\n\n import civis\n client = civis.APIClient()\n print(client.users.list_me()['username'])\n\nIf ``civis`` was installed correctly, this will print your Civis\nPlatform username.\n\nThe client has a soft dependency on ``pandas`` to support features such as\ndata type parsing. If you are using the ``io`` namespace to read or write\ndata from Civis, it is highly recommended that you install ``pandas`` and\nset ``use_pandas=True`` in functions that accept that parameter. To install\n``pandas``:\n\n.. code-block:: bash\n\n pip install pandas\n\nMachine learning features in the ``ml`` namespace have a soft dependency on\n``scikit-learn`` and ``pandas``. Install ``scikit-learn`` to\nexport your trained models from the Civis Platform or to\nprovide your own custom models. Use ``pandas`` to download model predictions\nfrom the Civis Platform. The ``civis.ml`` code\noptionally uses the `feather <https://github.com/wesm/feather>`_\nformat to transfer data from your local computer to Civis\nPlatform. Install these dependencies with\n\n.. code-block:: bash\n\n pip install scikit-learn\n pip install pandas\n pip install feather-format\n\n\nSome CivisML models have open-source dependencies in\naddition to ``scikit-learn``, which you may need if you want to\ndownload the model object. These dependencies are\n``civisml-extensions``, ``glmnet``, and ``muffnn``. Install these\ndependencies with\n\n.. code-block:: bash\n\n pip install civisml-extensions\n pip install glmnet\n pip install muffnn\n\n.. end-include-marker-installation-section\n\nUsage\n-----\n\n``civis`` includes a number of wrappers around the Civis API for\ncommon workflows.\n\n.. code-block:: python\n\n import civis\n df = civis.io.read_civis(table=\"my_schema.my_table\",\n database=\"database\",\n use_pandas=True)\n\nThe Civis API may also be directly accessed via the ``APIClient`` class.\n\n.. code-block:: python\n\n import civis\n client = civis.APIClient()\n database = client.databases.list()\n\nSee the `documentation <https://civis-python.readthedocs.io>`_ for a more\ncomplete user guide.\n\n\nBuilding Documentation\n----------------------\n\nBackground:\n\n* We use the Sphinx framework. The documentation source files are in ``docs/``.\n* All auto-generated files, including the HTML pages, are explicitly not versioned\n (see ``.gitignore``).\n\nFor the public documentation at https://civis-python.readthedocs.io:\n\n* The doc build is configured by ``.readthedocs.yaml``.\n Normally, even when we need to update the documentation or make a new release of civis-python,\n neither this configuration YAML file nor Civis's account on the Read the Docs site need\n any updates.\n* To update the documentation, the files under ``docs/`` can be updated as needed.\n If the \"API Resources\" pages need to be updated because the upstream Civis API has been updated,\n then the following need to happen:\n (i) the new Civis API updates must be accessible by a \"standard\" Civis Platform user,\n i.e., not behind a feature flag, and\n (ii) you'll need to locally run ``python tools/update_civis_api_spec.py`` to update\n ``civis_api_spec.json`` inside the ``civis`` Python package codebase.\n It is this JSON file that's the basis for the Civis API information on the \"API Resources\" pages.\n Regardless of which Civis API key you use to run ``python tools/update_civis_api_spec.py``,\n the updated ``civis_api_spec.json`` only contains Civis API information available to\n a standard Civis Platform user.\n* The URL https://civis-python.readthedocs.io auto-redirects to\n the \"stable\" URL https://civis-python.readthedocs.io/en/stable/ which reflects\n the most recent released civis-python version\n (every GitHub release with the tag \"vX.Y.Z\" triggers a new \"stable\" doc build\n on the Read The Docs site).\n In contrast, the \"latest\" URL https://civis-python.readthedocs.io/en/latest/ reflects\n the most recent commit to the upstream ``main`` branch of the civis-python codebase on GitHub.\n If there are doc changes (e.g., new or removed Civis API methods) that we'd really like to\n show up at the \"stable\" URL sooner rather than waiting for the next release with other code changes,\n we can make a patch release (i.e., increment the \"Z\" in \"vX.Y.Z\").\n\nThe doc build has its full dependencies listed in ``docs/requirements.txt``.\nTo update this file:\n\n* Install the latest version of ``pip-tools``: ``pip install --upgrade pip-tools``.\n* Run the ``pip-compile`` command at the top of ``docs/requirements.txt``, with the flag\n ``--upgrade`` added to upgrade all transitive dependencies as well.\n\nTo build the documentation locally, for testing and development:\n\n* Install the full doc-related dependencies: ``pip install -r docs/requirements.txt``.\n* Run ``sphinx-build -b html docs docs/build``.\n In case you would like for the \"API Resources\" page to locally show what a specific\n Civis Platform user would see from the Civis API\n (rather than use the available ``civis_api_spec.json`` for a standard Civis Platform user),\n set the environment variable ``CIVIS_API_KEY`` to this user's key\n and prepend this command with ``FETCH_REMOTE_RESOURCES=true``.\n\n\nCommand-line Interface (CLI)\n----------------------------\n\nAfter installing the Python package, you'll also have a ``civis`` command accessible from your shell. It surfaces a commandline interface to all of the regular Civis API endpoints, plus a few helpers. To get started, run ``civis --help``.\nPlease see the `CLI documentation <https://civis-python.readthedocs.io/en/stable/cli.html>`_ for more details.\n\n\nContributing\n------------\n\nSee `CONTRIBUTING.md <CONTRIBUTING.md>`_ for information about contributing to this project.\n\n\nLicense\n-------\n\nBSD-3\n\nSee `LICENSE.md <LICENSE.md>`_ for details.\n\n\nFor Maintainers\n---------------\n\nThe `tools <tools/>`_ directory contains scripts that civis-python maintainers can\nuse (and maintain...). Please see their docstrings for usage.\nNon-public information can be found by searching the internal documentation system\nor consulting the current maintainers.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Civis API Python Client",
"version": "2.4.3",
"project_urls": {
"Homepage": "https://www.civisanalytics.com",
"Source": "https://github.com/civisanalytics/civis-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "427104d9012741eea67831695855c8ca9ab785cd11bdcffd460698b4aabcab8b",
"md5": "18301e99a51f9190989940a82a394189",
"sha256": "efd355f6250fa4c8030ef0081fcdf6968c367767ef0e371c03cb690b5d8bda83"
},
"downloads": -1,
"filename": "civis-2.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "18301e99a51f9190989940a82a394189",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 510479,
"upload_time": "2025-01-13T19:09:24",
"upload_time_iso_8601": "2025-01-13T19:09:24.448750Z",
"url": "https://files.pythonhosted.org/packages/42/71/04d9012741eea67831695855c8ca9ab785cd11bdcffd460698b4aabcab8b/civis-2.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4103d91ab9c400ee6741bbcc0a2e6ae7b78ec160f40471e9a2527366563b8eae",
"md5": "ded95672fa796327cd50c2c473a7c6e6",
"sha256": "b9d434121c1065e192c9225878ea20a58d950554f1be449a4bad668bea1f501d"
},
"downloads": -1,
"filename": "civis-2.4.3.tar.gz",
"has_sig": false,
"md5_digest": "ded95672fa796327cd50c2c473a7c6e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 539668,
"upload_time": "2025-01-13T19:09:35",
"upload_time_iso_8601": "2025-01-13T19:09:35.877385Z",
"url": "https://files.pythonhosted.org/packages/41/03/d91ab9c400ee6741bbcc0a2e6ae7b78ec160f40471e9a2527366563b8eae/civis-2.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 19:09:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "civisanalytics",
"github_project": "civis-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "civis"
}
