Package: facespace
FaceSpace Python API ClientFaceSpace is a sophisticated Python package designed for developers to seamlessly interface with thevision.automa.oneAPI. It offers a comprehensive toolkit for logging, real-time data retrieval, and camera management. The package is built with asynchronous operations in mind, ensuring optimal performance in high-throughput applications.InstallationTo install FaceSpace, use the following pip command:pipinstallfacespaceThis package requires Python version 3.8 or higher.ConfigurationObtain your API key fromhttps://vision.automa.one. For security best practices, it is strongly advised to store this key as an environment variable.UsageSetting Up the ClientfromfacespaceimportLogsAPI,FaceSpaceErrorimportos# Utilize an environment variable for your API key to enhance security.api_key=os.getenv('FACESPACE_API_KEY')client=LogsAPI(api_key=api_key)Fetching LogsBasic Log Retrieval# Retrieve logs for a specified time range and camera.start_time='10:00:00 23/10/23'# Start of the log retrieval period.end_time='24/10/23'# End of the log retrieval period.camera_id='TestCamera'# Identifier for the camera.logs=client.get_logs_range(start_time=start_time,end_time=end_time,camera_id=camera_id)print(logs)When astart_timeis specified with only a date, the system defaults to the beginning of that day (00:00:00). In the absence of anend_time, logs are retrieved from thestart_timeto the last available entry. If acamera_idis not provided, the system will collect logs across all cameras. Should bothstart_timeandend_timebe omitted, the system will return the complete set of logs.Note: Time must be provided in UTC only (for now).Advanced Log Retrieval# Fetch logs with additional configurations.client=LogsAPI(api_key=api_key,log_to_file=True,# This enables the logging of data to a file.webhook_url='https://yourwebhook.url',# Logs will be posted to this webhook URL.additional_headers={'Custom-Header':'Value'},# Custom headers included in the webhook post.post_realtime=False# Determines whether real-time logs are posted to the webhook.)logs=client.get_logs_range(start_time=start_time,end_time=end_time)print(logs)Thelog_to_fileoption, when set toTrue, logs will be saved to a file, which is useful for persistent storage and later analysis. Thewebhook_urlallows for integration with external systems for processing or monitoring. Ifadditional_headersare provided, they will be included in the webhook post, allowing for custom integration. Settingpost_realtimetoFalsewill prevent real-time logs from being sent to the webhook.Real-time LogsBasic Real-time Log Streaming# Stream real-time logs using a context manager.withclient:forloginclient.get_realtime_logs(refresh=1.0):# Refresh rate set to 1 second.print(log)Therefreshparameter controls the rate at which real-time logs are fetched. If not provided, a default value is used. If set too low, it may overwhelm the system with rapid data flow.Limited Real-time Log Streaming# Stream a limited number of real-time logs.forloginclient.get_realtime_logs(refresh=0.5,limit=10):# Fetch 10 logs with a half-second pause.print(log)Thelimitparameter controls the number of real-time logs fetched. If omitted, the stream will continue indefinitely until manually stopped.High-Speed Real-time Log Streaming# Stream real-time logs at a high refresh rate.forloginclient.get_realtime_logs(refresh=0.1):# Set a very fast refresh rate.print(log)Arefreshrate of 0.1 seconds is extremely fast and should only be used if the system can handle such rapid data flow.Error HandlingFaceSpace provides custom exceptions for robust error management. When using the FaceSpace API client, it's important to understand the various errors that can occur and how to handle them. Here's a breakdown of potential errors and their typical causes:APIKeyErrorThis error is raised when the API key provided is either missing or invalid. It's crucial to ensure that the API key is correctly set as an environment variable or passed directly to the client. An invalid API key could be due to a typo, incorrect key, or the key not being generated or activated properly on thevision.automa.oneportal.DateParseErrorThis occurs when the date format provided does not match the expected format (HH:MM:SS DD/MM/YY). If only the date is provided without the time, it should still follow theDD/MM/YYformat. This error can be avoided by ensuring the date strings passed to the API are in the correct format.HTTPRequestErrorAn HTTP request error happens when there's a problem with the network connection, the API endpoint is unreachable, or the server fails to respond. This could be due to network issues on the client side, downtime on the API server, or incorrect endpoint URLs.StopLogsSignalThis is a control signal rather than an error. It's raised to stop the retrieval of logs, which could be part of normal operation or a response to a specific command from the server indicating that the client should cease log retrieval.InvalidUsageErrorThis error is raised when methods are used incorrectly. For example, if theget_realtime_logsmethod is called without being in aforloop, or if the parameters provided to any method do not meet the required criteria (like missing mandatory fields or providing parameters in an incorrect type or format).General Error HandlingTheFaceSpaceErroris a base class for all custom exceptions. It's used in a broadtry...exceptblock to catch any of the specific errors mentioned above. When an error is caught, it's good practice to log the error message and, if necessary, perform cleanup operations such as stopping real-time log streams to prevent partial or corrupted data processing.Here's an example of how you might handle errors in a typical use case:try:# Attempt to fetch logs or stream real-time logs.# ...exceptFaceSpaceErrorase:print(f'Error occurred:{e}')client.stop_realtime_logs()# Properly stop the real-time log stream.Advanced ConfigurationWebhook Integration: Direct logs to a specified webhook URL for external processing or monitoring.Custom Headers: Send additional headers with your webhook requests for customized integration.Real-time Log Posting: Toggle the posting of real-time logs to your webhook endpoint.File Logging: Enable logging to a file for persistent storage and later review.Log Level: Adjust the verbosity of the logs for different environments, such as debugging or production.Comprehensive ExamplesWebhook Configurationclient=LogsAPI(api_key=api_key,webhook_url='https://yourwebhook.url',# Your webhook endpoint.additional_headers={'Custom-Header':'Value'},# Any additional headers you require.post_logs=True# Enable posting logs to the webhook URL.)Note: By default,post_logsis set toFalseto prevent the transmission of large static blocks of data to the webhook.File Logging and Log Levelclient=LogsAPI(api_key=api_key,log_to_file=True,# Enable file logging.log_level=logging.DEBUG# Set log level to DEBUG for verbose output.)Example Code: Fetching Logs for an Entire DayfromfacespaceimportLogsAPI,FaceSpaceErrorimportos# Initialize the client with your API keyapi_key=os.getenv('YOUR_API_KEY')client=LogsAPI(api_key=api_key)# Define the date for which you want to fetch logs# The time is omitted, so logs from the start to the end of the day are fetched.date='23/10/23'# Format: DD/MM/YYtry:# Fetch logs for the entire day for a specific camera.camera_id='TestCamera'logs=client.get_logs_range(start_time=date,end_time=date,camera_id=camera_id)print(logs)# If camera_id is not provided, logs for all cameras will be fetched.all_camera_logs=client.get_logs_range(start_time=date,end_time=date)print(all_camera_logs)exceptFaceSpaceErrorase:print(f'An error occurred:{e}')# Additional error handling can be implemented here.Example Output Print# Example output when get_logs_range is printed for a specific camera{'TestCamera':['Alice @ 00:05:22 23/10/23','Bob @ 11:15:47 23/10/23',...'Eve @ 23:59:59 23/10/23']}# Example output when get_logs_range is printed for all cameras{'Camera1':['Alice @ 00:05:22 23/10/23','Bob @ 11:15:47 23/10/23'],'Camera2':['Charlie @ 07:30:00 23/10/23','Dana @ 18:45:30 23/10/23'],...}# Example output for real-time logs{'Camera1':['Alice','Bob'],'Camera2':['Charlie','Dana']}SupportFor support, issues, or feature requests, please file an issue on ourGitHub Issues page.LicenseFaceSpace API Client is released under the MIT License. See the LICENSE file in the repository for more details.