Skip to main content

Python API client for NeuroIO

PyPI version codecov License Downloads Code style: black Imports: isort


Read Latest Documentation - Browse GitHub Code Repository


This library strives to be a complete mirror of official NeuroIO API in terms of methods and interfaces.

Official latest API documentation can be found here.

For your convenience, you can make API calls using sync or async (asyncio) interface.

Installation

pip install neuroio

Note that it is always recommended pinning version of your installed packages.

Usage example (sync)

An example of how to create a source:

from neuroio import Client


if __name__ == '__main__':
    # api_token is just str with your API token from NeuroIO
    api_token = "abcd012345"
    # Now create instance of Client. There should be only one per process.
    client = Client(api_token=api_token)
    # Issue API request to create source
    client.sources.create(name="test_name")

Now that we have our source created, we can create person inside that source:

from neuroio import Client


def create_persons_example(client: Client):
    source_name = "test_name"
    with open("image.png", "rb") as f:
        response = client.persons.create(
            image=f,
            source=source_name,
            facesize=1000,
            create_on_ha=True,
            create_on_junk=True,
            identify_asm=True
        )
    print("Persons Create Response:\n", response.json(), flush=True)


if __name__ == '__main__':
    # api_token is just str with your API token from NeuroIO
    api_token = "abcd012345"
    # Now create instance of Client. There should be only one per process.
    client = Client(api_token=api_token)
    # Issue API request to create a person
    create_persons_example(client)

Now that we have our source & person created, we can search for persons:

from neuroio import Client


def search_persons_example(client: Client):
    with open("image.png", "rb") as f:
        response = client.persons.search(
            image=f,
            identify_asm=True
        )
    print("Persons Search Response:\n", response.json(), flush=True)


if __name__ == '__main__':
    # api_token is just str with your API token from NeuroIO
    api_token = "abcd012345"
    # Now create instance of Client. There should be only one per process.
    client = Client(api_token=api_token)
    # Issue API request to search persons
    search_persons_example(client)

An example of how to listen for events:

import asyncio
import json
import logging
import signal

from neuroio import EventListener


async def event_handler_func(event_message: str):
    # NOTE: this must be awaitable and accept single param Union[str, bytes]
    json_message = json.loads(event_message)
    is_ping_response = "PING" in json_message.keys()
    is_auth_response = "auth" in json_message.keys()
    is_error_response = "error" in json_message.keys()
    if is_ping_response:
        if json_message["PING"] != "PONG":
            # something is wrong with socket connection
            raise RuntimeError()
        else:
            # this is correct pong response on our periodic pings
            logging.info("Connection is alive")
    elif is_auth_response:
        logging.info("Authorized successfully")
    elif is_error_response:
        # something is wrong with provided token
        logging.info(json_message["error"], flush=True)
    else:
        # this must be event about entry itself
        # now you can inspect json_message for information about that
        logging.info(json_message["data"]["face_image"])


async def shutdown(signal, loop):
    """Cleanup tasks tied to the service's shutdown."""
    logging.info(f"Received exit signal {signal.name}...")
    tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]

    [task.cancel() for task in tasks]

    logging.info(f"Cancelling {len(tasks)} outstanding tasks")
    await asyncio.gather(*tasks, return_exceptions=True)
    loop.stop()


if __name__ == "__main__":
    logging.getLogger().setLevel(logging.INFO)
    
    # NOTE: You are advised to hook-up uvloop here for improved performance
    
    api_token = "1234567890"
    events_listener = EventListener(
        api_token=api_token, event_handler_func=event_handler_func
    )

    loop = asyncio.get_event_loop()
    # May want to catch other signals too
    signals = (signal.SIGHUP, signal.SIGTERM, signal.SIGINT)
    for s in signals:
        loop.add_signal_handler(
            s, lambda _s=s: asyncio.create_task(shutdown(_s, loop))
        )

    try:
        loop.create_task(events_listener.listen())
        loop.run_forever()
    finally:
        loop.close()
        logging.info("Successfully shutdown")

For more examples and usage, please refer to the docs.

Development setup

To install all the development requirements:

pip install --upgrade pip
pip install poetry
poetry install --no-root

To run linters & test suite:

./scripts/test.sh

Release History

  • 0.1.0
    • Support for WebSocket Events
    • Drop Python 3.6 support
  • 0.0.9
    • Fixes to the sources API in terms of required fields
  • 0.0.8
    • Updated library to latest API version (at the time of this release - 1.3.1)
    • Updated README & docs
  • 0.0.7
    • Updated library to latest API version (at the time of this release - 1.3.0)
    • Updated requirements
    • Updated README & docs
  • 0.0.6
    • Updated library to latest API version (at the time of this release - 1.2.1)
    • Updated README & docs
  • 0.0.5
    • Fixed persistent connection problems
    • Updated requirements
    • Codebase cleanup
  • 0.0.4
    • Changed the way how we treat httpx connection - now we don't close it after every request (which was supposedly right way in httpx docs)
  • 0.0.3
    • Updated httpx version, disabled cruft check since it just messes up project files

License

Distributed under the MIT license. See LICENSE for more information.

Contributing

  1. Fork it (https://github.com/yourname/yourproject/fork)
  2. Create your feature branch (git checkout -b feature/fooBar)
  3. Commit your changes (git commit -am 'Add some fooBar')
  4. Push to the branch (git push origin feature/fooBar)
  5. Create a new Pull Request

Metadata

Release files for neuroio 0.1.2

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

Source distribution (sdist)

Source distribution for neuroio 0.1.2
File Size Uploaded Provenance Actions
neuroio-0.1.2.tar.gz 14.8 kB Without provenance Details for neuroio-0.1.2.tar.gz

Built distribution (wheel)

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

Total release size: 37.4 kB

Release files / neuroio-0.1.2.tar.gz

Download URL neuroio-0.1.2.tar.gz
Size 14.8 kB
Tags Source
SHA-256 checksum
How to use checksums
fe4e27e673f6bde9649e310552aa2fdaf14379654c523c4727561fc2ed236069
BLAKE2b-256 checksum
How to use checksums
34c97ee6c87002c6b9e1815b10a166f5d13446be7dada3ec654176b913eaf7e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.4.2 CPython/3.9.6 Darwin/22.3.0

Release files / neuroio-0.1.2-py3-none-any.whl

Download URL neuroio-0.1.2-py3-none-any.whl
Size 22.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d2478c93399aa2e02b68d64c94041d40ae806fae1098b064c3d4b5cd696e4c2
BLAKE2b-256 checksum
How to use checksums
d9c1960940b6cd2ffe6964c69b7f802e9ee37f5be9eb08647350f25a8fd6e9a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via poetry/1.4.2 CPython/3.9.6 Darwin/22.3.0

Security for neuroio 0.1.2

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.

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