acled 0.1.4__py3-none-any.whl

acled/__init__.py

@@ -0,0 +1 @@
+from .clients import AcledClient

acled/clients/__init__.py

@@ -0,0 +1,3 @@
+from .client import AcledClient
+from .acled_data_client import AcledDataClient
+from .base_http_client import BaseHttpClient

acled/clients/acled_data_client.py

@@ -0,0 +1,223 @@
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+from datetime import datetime, date
+
+from .base_http_client import BaseHttpClient
+from ..models.data_models import AcledEvent
+from ..models.enums import ExportType
+from ..exceptions import ApiError
+
+
+class AcledDataClient(BaseHttpClient):
+    """
+    Client for interacting with the ACLED main dataset endpoint.
+    """
+
+    def __init__(self, api_key: str, email: str):
+        super().__init__(api_key, email)
+        self.endpoint = "/acled/read"
+
+    def get_data(
+        self,
+        event_id_cnty: Optional[str] = None,
+        event_date: Optional[Union[str, date]] = None,
+        year: Optional[int] = None,
+        time_precision: Optional[int] = None,
+        disorder_type: Optional[str] = None,
+        event_type: Optional[str] = None,
+        sub_event_type: Optional[str] = None,
+        actor1: Optional[str] = None,
+        assoc_actor_1: Optional[str] = None,
+        inter1: Optional[int] = None,
+        actor2: Optional[str] = None,
+        assoc_actor_2: Optional[str] = None,
+        inter2: Optional[int] = None,
+        interaction: Optional[int] = None,
+        civilian_targeting: Optional[str] = None,
+        iso: Optional[int] = None,
+        region: Optional[int] = None,
+        country: Optional[str] = None,
+        admin1: Optional[str] = None,
+        admin2: Optional[str] = None,
+        admin3: Optional[str] = None,
+        location: Optional[str] = None,
+        latitude: Optional[float] = None,
+        longitude: Optional[float] = None,
+        geo_precision: Optional[int] = None,
+        source: Optional[str] = None,
+        source_scale: Optional[str] = None,
+        notes: Optional[str] = None,
+        fatalities: Optional[int] = None,
+        timestamp: Optional[Union[int, str, date]] = None,
+        export_type: Optional[str | ExportType] = ExportType.JSON,
+        limit: int = 50,
+        page: Optional[int] = None,
+        query_params: Optional[Dict[str, Any]] = None,
+    ) -> List[AcledEvent]:
+        """
+        Retrieves ACLED data based on the provided filters.
+
+        Args:
+            event_id_cnty (Optional[str]): Filter by event ID country (supports LIKE).
+            event_date (Optional[Union[str, date]]): Filter by event date (format 'yyyy-mm-dd').
+            year (Optional[int]): Filter by year.
+            time_precision (Optional[int]): Filter by time precision.
+            disorder_type (Optional[str]): Filter by disorder type (supports LIKE).
+            event_type (Optional[str]): Filter by event type (supports LIKE).
+            sub_event_type (Optional[str]): Filter by sub-event type (supports LIKE).
+            actor1 (Optional[str]): Filter by actor1 (supports LIKE).
+            assoc_actor_1 (Optional[str]): Filter by associated actor1 (supports LIKE).
+            inter1 (Optional[int]): Filter by inter1 code.
+            actor2 (Optional[str]): Filter by actor2 (supports LIKE).
+            assoc_actor_2 (Optional[str]): Filter by associated actor2 (supports LIKE).
+            inter2 (Optional[int]): Filter by inter2 code.
+            interaction (Optional[int]): Filter by interaction code.
+            civilian_targeting (Optional[str]): Filter by civilian targeting (supports LIKE).
+            iso (Optional[int]): Filter by ISO country code.
+            region (Optional[int]): Filter by region number.
+            country (Optional[str]): Filter by country name.
+            admin1 (Optional[str]): Filter by admin1 (supports LIKE).
+            admin2 (Optional[str]): Filter by admin2 (supports LIKE).
+            admin3 (Optional[str]): Filter by admin3 (supports LIKE).
+            location (Optional[str]): Filter by location (supports LIKE).
+            latitude (Optional[float]): Filter by latitude.
+            longitude (Optional[float]): Filter by longitude.
+            geo_precision (Optional[int]): Filter by geographic precision.
+            source (Optional[str]): Filter by source (supports LIKE).
+            source_scale (Optional[str]): Filter by source scale (supports LIKE).
+            notes (Optional[str]): Filter by notes (supports LIKE).
+            fatalities (Optional[int]): Filter by number of fatalities.
+            timestamp (Optional[Union[int, str, date]]): Filter by timestamp (>= value).
+            export_type (Optional[str]): Specify the export type ('json', 'xml', 'csv', etc.).
+            query_params (Optional[Dict[str, Any]]): Additional query parameters (e.g., to use '_where' suffix).
+
+        Returns:
+            List[AcledEvent]: A list of ACLED events matching the filters.
+
+        Raises:
+            ApiError: If there's an error with the API request or response.
+        """
+        params: Dict[str, Any] = query_params.copy() if query_params else {}
+
+        # Map arguments to query parameters, handling type conversions
+        if event_id_cnty is not None:
+            params['event_id_cnty'] = event_id_cnty
+        if event_date is not None:
+            if isinstance(event_date, date):
+                event_date_str = event_date.strftime('%Y-%m-%d')
+            else:
+                event_date_str = event_date
+            params['event_date'] = event_date_str
+        if year is not None:
+            params['year'] = str(year)
+        if time_precision is not None:
+            params['time_precision'] = str(time_precision)
+        if disorder_type is not None:
+            params['disorder_type'] = disorder_type
+        if event_type is not None:
+            params['event_type'] = event_type
+        if sub_event_type is not None:
+            params['sub_event_type'] = sub_event_type
+        if actor1 is not None:
+            params['actor1'] = actor1
+        if assoc_actor_1 is not None:
+            params['assoc_actor_1'] = assoc_actor_1
+        if inter1 is not None:
+            params['inter1'] = str(inter1)
+        if actor2 is not None:
+            params['actor2'] = actor2
+        if assoc_actor_2 is not None:
+            params['assoc_actor_2'] = assoc_actor_2
+        if inter2 is not None:
+            params['inter2'] = str(inter2)
+        if interaction is not None:
+            params['interaction'] = str(interaction)
+        if civilian_targeting is not None:
+            params['civilian_targeting'] = civilian_targeting
+        if iso is not None:
+            params['iso'] = str(iso)
+        if region is not None:
+            params['region'] = str(region)
+        if country is not None:
+            params['country'] = country
+        if admin1 is not None:
+            params['admin1'] = admin1
+        if admin2 is not None:
+            params['admin2'] = admin2
+        if admin3 is not None:
+            params['admin3'] = admin3
+        if location is not None:
+            params['location'] = location
+        if latitude is not None:
+            params['latitude'] = str(latitude)
+        if longitude is not None:
+            params['longitude'] = str(longitude)
+        if geo_precision is not None:
+            params['geo_precision'] = str(geo_precision)
+        if source is not None:
+            params['source'] = source
+        if source_scale is not None:
+            params['source_scale'] = source_scale
+        if notes is not None:
+            params['notes'] = notes
+        if fatalities is not None:
+            params['fatalities'] = str(fatalities)
+        if timestamp is not None:
+            if isinstance(timestamp, date):
+                timestamp_str = timestamp.strftime('%Y-%m-%d')
+            else:
+                timestamp_str = str(timestamp)
+            params['timestamp'] = timestamp_str
+        if export_type is not None:
+            if isinstance(export_type, ExportType):
+                params['export_type'] = export_type.value
+            else:
+                params['export_type'] = export_type
+
+        if isinstance(page, int):
+            params['page'] = page
+        params['limit'] = limit if limit else 50
+
+
+        # Perform the API request
+        try:
+            response = self._get(self.endpoint, params=params)
+            if response.get('success'):
+                event_list = response.get('data', [])
+                return [self._parse_event(event) for event in event_list]
+            else:
+                error_message = response.get('error', [{'message': 'Unknown error'}])[0]['message']
+                raise ApiError(f"API Error: {error_message}")
+        except requests.HTTPError as e:
+            raise ApiError(f"HTTP Error: {str(e)}")
+
+    def _parse_event(self, event_data: Dict[str, Any]) -> AcledEvent:
+        """
+        Parses raw event data into an AcledEvent TypedDict.
+
+        Args:
+            event_data (Dict[str, Any]): Raw event data.
+
+        Returns:
+            AcledEvent: Parsed ACLED event.
+
+        Raises:
+            ValueError: If there's an error during parsing.
+        """
+        try:
+            event_data['event_date'] = datetime.strptime(
+                event_data['event_date'], '%Y-%m-%d'
+            ).date()
+            event_data['year'] = int(event_data['year'])
+            event_data['time_precision'] = int(event_data.get('time_precision', 0))
+            event_data['latitude'] = float(event_data.get('latitude', 0.0))
+            event_data['longitude'] = float(event_data.get('longitude', 0.0))
+            event_data['fatalities'] = int(event_data.get('fatalities', 0))
+            event_data['timestamp'] = datetime.fromtimestamp(
+                int(event_data['timestamp'])
+            )
+
+            return event_data
+        except (ValueError, KeyError) as e:
+            raise ValueError(f"Error parsing event data: {str(e)}")

acled/clients/actor_client.py

@@ -0,0 +1,113 @@
+from typing import Any, Dict, List, Optional, Union
+import requests
+from datetime import datetime, date
+
+from .base_http_client import BaseHttpClient
+from ..models.data_models import Actor
+from ..models.enums import ExportType
+from ..exceptions import ApiError
+
+
+class ActorClient(BaseHttpClient):
+    """
+    Client for interacting with the ACLED actor endpoint.
+    """
+
+    def __init__(self, api_key: str, email: str):
+        super().__init__(api_key, email)
+        self.endpoint = "/actor/read"
+
+    def get_data(
+        self,
+        actor_name: Optional[str] = None,
+        first_event_date: Optional[Union[str, date]] = None,
+        last_event_date: Optional[Union[str, date]] = None,
+        event_count: Optional[int] = None,
+        export_type: Optional[Union[str, ExportType]] = ExportType.JSON,
+        limit: int = 50,
+        page: Optional[int] = None,
+        query_params: Optional[Dict[str, Any]] = None,
+    ) -> List[Actor]:
+        """
+        Retrieves Actor data based on the provided filters.
+
+        Args:
+            actor_name (Optional[str]): Filter by actor name (supports LIKE).
+            first_event_date (Optional[Union[str, date]]): Filter by first event date (format 'yyyy-mm-dd').
+            last_event_date (Optional[Union[str, date]]): Filter by last event date (format 'yyyy-mm-dd').
+            event_count (Optional[int]): Filter by event count.
+            export_type (Optional[str | ExportType]): Specify the export type ('json', 'xml', 'csv', etc.).
+            limit (int): Number of records to retrieve (default is 50).
+            page (Optional[int]): Page number for pagination.
+            query_params (Optional[Dict[str, Any]]): Additional query parameters.
+
+        Returns:
+            List[Actor]: A list of Actors matching the filters.
+
+        Raises:
+            ApiError: If there's an error with the API request or response.
+        """
+        params: Dict[str, Any] = query_params.copy() if query_params else {}
+
+        # Map arguments to query parameters, handling type conversions
+        if actor_name is not None:
+            params['actor_name'] = actor_name
+        if first_event_date is not None:
+            if isinstance(first_event_date, date):
+                params['first_event_date'] = first_event_date.strftime('%Y-%m-%d')
+            else:
+                params['first_event_date'] = first_event_date
+        if last_event_date is not None:
+            if isinstance(last_event_date, date):
+                params['last_event_date'] = last_event_date.strftime('%Y-%m-%d')
+            else:
+                params['last_event_date'] = last_event_date
+        if event_count is not None:
+            params['event_count'] = str(event_count)
+        if export_type is not None:
+            if isinstance(export_type, ExportType):
+                params['export_type'] = export_type.value
+            else:
+                params['export_type'] = export_type
+        params['limit'] = str(limit) if limit else '50'
+        if page is not None:
+            params['page'] = str(page)
+
+        # Perform the API request
+        try:
+            response = self._get(self.endpoint, params=params)
+            if response.get('success'):
+                actor_list = response.get('data', [])
+                return [self._parse_actor(actor) for actor in actor_list]
+            else:
+                error_info = response.get('error', [{'message': 'Unknown error'}])[0]
+                error_message = error_info.get('message', 'Unknown error')
+                raise ApiError(f"API Error: {error_message}")
+        except requests.HTTPError as e:
+            raise ApiError(f"HTTP Error: {str(e)}")
+
+    def _parse_actor(self, actor_data: Dict[str, Any]) -> Actor:
+        """
+        Parses raw actor data into an Actor TypedDict.
+
+        Args:
+            actor_data (Dict[str, Any]): Raw actor data.
+
+        Returns:
+            Actor: Parsed Actor.
+
+        Raises:
+            ValueError: If there's an error during parsing.
+        """
+        try:
+            actor_data['first_event_date'] = datetime.strptime(
+                actor_data['first_event_date'], '%Y-%m-%d'
+            ).date()
+            actor_data['last_event_date'] = datetime.strptime(
+                actor_data['last_event_date'], '%Y-%m-%d'
+            ).date()
+            actor_data['event_count'] = int(actor_data.get('event_count', 0))
+
+            return actor_data
+        except (ValueError, KeyError) as e:
+            raise ValueError(f"Error parsing actor data: {str(e)}")

acled/clients/actor_type_client.py

@@ -0,0 +1,117 @@
+from typing import Any, Dict, List, Optional, Union
+import requests
+from datetime import datetime, date
+
+from .base_http_client import BaseHttpClient
+from ..models.data_models import ActorType
+from ..models.enums import ExportType
+from ..exceptions import ApiError
+
+class ActorTypeClient(BaseHttpClient):
+    """
+    Client for interacting with the ACLED actor type endpoint.
+    """
+
+    def __init__(self, api_key: str, email: str):
+        super().__init__(api_key, email)
+        self.endpoint = "/actortype/read"
+
+    def get_data(
+        self,
+        actor_type_id: Optional[int] = None,
+        actor_type_name: Optional[str] = None,
+        first_event_date: Optional[Union[str, date]] = None,
+        last_event_date: Optional[Union[str, date]] = None,
+        event_count: Optional[int] = None,
+        export_type: Optional[Union[str, ExportType]] = ExportType.JSON,
+        limit: int = 50,
+        page: Optional[int] = None,
+        query_params: Optional[Dict[str, Any]] = None,
+    ) -> List[ActorType]:
+        """
+        Retrieves Actor Type data based on the provided filters.
+
+        Args:
+            actor_type_id (Optional[int]): Filter by actor type ID.
+            actor_type_name (Optional[str]): Filter by actor type name (supports LIKE).
+            first_event_date (Optional[Union[str, date]]): Filter by first event date (format 'yyyy-mm-dd').
+            last_event_date (Optional[Union[str, date]]): Filter by last event date (format 'yyyy-mm-dd').
+            event_count (Optional[int]): Filter by event count (default query is >=).
+            export_type (Optional[str | ExportType]): Specify the export type ('json', 'xml', 'csv', etc.).
+            limit (int): Number of records to retrieve (default is 50).
+            page (Optional[int]): Page number for pagination.
+            query_params (Optional[Dict[str, Any]]): Additional query parameters.
+
+        Returns:
+            List[ActorType]: A list of Actor Types matching the filters.
+
+        Raises:
+            ApiError: If there's an error with the API request or response.
+        """
+        params: Dict[str, Any] = query_params.copy() if query_params else {}
+
+        # Map arguments to query parameters, handling type conversions
+        if actor_type_id is not None:
+            params['actor_type_id'] = str(actor_type_id)
+        if actor_type_name is not None:
+            params['actor_type_name'] = actor_type_name
+        if first_event_date is not None:
+            if isinstance(first_event_date, date):
+                params['first_event_date'] = first_event_date.strftime('%Y-%m-%d')
+            else:
+                params['first_event_date'] = first_event_date
+        if last_event_date is not None:
+            if isinstance(last_event_date, date):
+                params['last_event_date'] = last_event_date.strftime('%Y-%m-%d')
+            else:
+                params['last_event_date'] = last_event_date
+        if event_count is not None:
+            params['event_count'] = str(event_count)
+        if export_type is not None:
+            if isinstance(export_type, ExportType):
+                params['export_type'] = export_type.value
+            else:
+                params['export_type'] = export_type
+        params['limit'] = str(limit) if limit else '50'
+        if page is not None:
+            params['page'] = str(page)
+
+        # Perform the API request
+        try:
+            response = self._get(self.endpoint, params=params)
+            if response.get('success'):
+                actor_type_list = response.get('data', [])
+                return [self._parse_actor_type(actor_type) for actor_type in actor_type_list]
+            else:
+                error_info = response.get('error', [{'message': 'Unknown error'}])[0]
+                error_message = error_info.get('message', 'Unknown error')
+                raise ApiError(f"API Error: {error_message}")
+        except requests.HTTPError as e:
+            raise ApiError(f"HTTP Error: {str(e)}")
+
+    def _parse_actor_type(self, actor_type_data: Dict[str, Any]) -> ActorType:
+        """
+        Parses raw actor type data into an ActorType TypedDict.
+
+        Args:
+            actor_type_data (Dict[str, Any]): Raw actor type data.
+
+        Returns:
+            ActorType: Parsed ActorType.
+
+        Raises:
+            ValueError: If there's an error during parsing.
+        """
+        try:
+            actor_type_data['actor_type_id'] = int(actor_type_data.get('actor_type_id', 0))
+            actor_type_data['first_event_date'] = datetime.strptime(
+                actor_type_data['first_event_date'], '%Y-%m-%d'
+            ).date()
+            actor_type_data['last_event_date'] = datetime.strptime(
+                actor_type_data['last_event_date'], '%Y-%m-%d'
+            ).date()
+            actor_type_data['event_count'] = int(actor_type_data.get('event_count', 0))
+
+            return actor_type_data  # This will be of type ActorType
+        except (ValueError, KeyError) as e:
+            raise ValueError(f"Error parsing actor type data: {str(e)}")

acled/clients/base_http_client.py

@@ -0,0 +1,54 @@
+import requests
+from typing import Any, Dict, Optional
+from os import environ
+from ..exceptions import AcledMissingAuthError
+from ..log import AcledLogger
+
+
+class BaseHttpClient(object):
+    """
+    A base HTTP client that provides basic GET and POST request functionality.
+    """
+    BASE_URL = environ.get("ACLED_API_HOST", "https://api.acleddata.com")
+
+    def __init__(self, api_key: Optional[str] = None, email: Optional[str] = None):
+        self.api_key = api_key if api_key else environ.get("ACLED_API_KEY")
+        if not self.api_key:
+            raise AcledMissingAuthError("API key is required")
+        self.email = email if email else environ.get("ACLED_EMAIL")
+        if not self.email:
+            raise AcledMissingAuthError("Email is required")
+        self.session = requests.Session()
+        self.session.headers.update({'Content-Type': 'application/json'})
+        self.log = AcledLogger().get_logger()
+
+    def _get(
+            self, endpoint: str, params: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        if params is None:
+            params = {}
+        # Include API key and email in all requests
+        params['key'] = self.api_key
+        params['email'] = self.email
+        url = f"{self.BASE_URL}{endpoint}"
+
+        self.log.debug(f"Constructed URL: {url}")
+        self.log.debug(f"Query Parameters: {params}")
+
+        response = self.session.get(url, params=params)
+        response.raise_for_status()
+        self.log.debug(f"Response content:\n{response.content}")
+        return response.json()
+
+    def _post(
+            self, endpoint: str, data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        if data is None:
+            data = {}
+        # Include API key and email in all requests
+        data['key'] = self.api_key
+        data['email'] = self.email
+        url = f"{self.BASE_URL}{endpoint}"
+        response = self.session.post(url, json=data)
+        response.raise_for_status()
+        return response.json()

acled/clients/client.py

@@ -0,0 +1,71 @@
+from typing import Optional
+
+from .acled_data_client import AcledDataClient
+from .actor_client import ActorClient
+from .actor_type_client import ActorTypeClient
+from .country_client import CountryClient
+from .region_client import RegionClient
+
+
+class AcledClient:
+    """
+    Main ACLED client that provides access to different API endpoints.
+
+    This client aggregates several sub-clients to provide a relatively complete interface for
+    interacting with the ACLED API. Each sub-client is responsible for a specific endpoint,
+    making it easier to organize and manage the API interactions while still providing a
+    single point of entry.
+
+    Methods:
+        get_data:
+            Returns:
+                Function to fetch the ACLED data.
+
+        get_actor_data:
+            Returns:
+                Function to fetch the actor data.
+
+        get_actor_type_data:
+            Returns:
+                Function to fetch the actor type data.
+
+        get_country_data:
+            Returns:
+                Function to fetch country data.
+
+        get_region_data:
+            Returns:
+                Function to fetch region data.
+    """
+
+    def __init__(
+            self,
+            api_key: Optional[str] = None,
+            email: Optional[str] = None
+    ):
+        self._acled_data_client = AcledDataClient(api_key, email)
+        self._actor_client = ActorClient(api_key, email)
+        self._country_client = CountryClient(api_key, email)
+        self._region_client = RegionClient(api_key, email)
+        self._actor_type_client = ActorTypeClient(api_key, email)
+
+
+    @property
+    def get_data(self):
+        return self._acled_data_client.get_data
+
+    @property
+    def get_actor_data(self):
+        return self._actor_client.get_data
+
+    @property
+    def get_actor_type_data(self):
+        return self._actor_type_client.get_data
+
+    @property
+    def get_country_data(self):
+        return self._country_client.get_data
+
+    @property
+    def get_region_data(self):
+        return self._region_client.get_data