Merge changes for docs.

.github/CODEOWNERS

@@ -1,4 +1,7 @@
 # These owners are the default owners for everything in the repo.
 # Unless a later match takes precedence,
 # These owners will be requested for review when someone opens a pull request.
-* @GrandMoff100
+* @GrandMoff100
+
+# Custom CSS Styling
+docs/static/css/custom.css @FoxNerdSaysMoo

.github/workflows/code_rules.yml

@@ -2,6 +2,8 @@ name: Code Standards
 
 on:
   push: # Comment this line to trigger action only on pull-requests (not recommended if you don't pay for GH Actions)
+    paths:
+      - "**.py"
   pull_request:
     branches:
       - master

.github/workflows/codeql-analysis.yml

@@ -14,6 +14,8 @@ name: "CodeQL"
 on:
   push:
     branches: [dev]
+    paths:
+      - "**.py"
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [dev]

.github/workflows/python-publish.yml

@@ -24,7 +24,4 @@ jobs:
         env:
           TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
           TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
-        run: |
-          poetry publish --build \
-            --username $TWINE_USERNAME \
-            --password $TWINE_PASSWORD
+        run: poetry publish --build -u "$TWINE_USERNAME" -p "$TWINE_PASSWORD"

.mega-linter.yml

@@ -5,7 +5,9 @@ APPLY_FIXES: all # all, none, or list of linter keys
 DISABLE:
   - PYTHON
   - COPYPASTE
+DISABLE_LINTERS:
+  - SPELL_CSPELL
 SHOW_ELAPSED_TIME: true
 FILEIO_REPORTER: true
 RST_FILTER_REGEX_EXCLUDE: "(:resource:`.+`)"
-DISABLE_ERRORS: true # Uncomment if you want MegaLinter to detect errors but not block CI to pass
+# DISABLE_ERRORS: true # Uncomment if you want MegaLinter to detect errors but not block CI to pass

CHANGELOG.md

@@ -27,7 +27,7 @@
 ## v2.3.0
 
 - Bug fixes (see closed issues between releases)
-- Added global request kwargs parameter to Client objects (see [docs](homeassistantapi.rtfd.io/en/latest/api.html#homeassistant_api.Client))
+- Added global request kwargs parameter to Client objects (see [docs](https://homeassistantapi.rtfd.io/en/latest/api.html#homeassistant_api.Client))
 
 ## v2.2.0
 

README.md

@@ -1,13 +1,12 @@
 # HomeassistantAPI
 
 ![Lines of code](https://img.shields.io/tokei/lines/github/GrandMoff100/HomeassistantAPI?style=for-the-badge)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/HomeAssistant-API?style=for-the-badge)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/HomeAssistant-API?style=for-the-badge)](https://pypi.org/project/homeassistant_api)
 ![GitHub commits since latest release (by date including pre-releases)](https://img.shields.io/github/commits-since/GrandMoff100/HomeassistantAPI/latest/dev?include_prereleases&style=for-the-badge)
-![Read the Docs (version)](https://img.shields.io/readthedocs/homeassistantapi/stable?style=for-the-badge)
-![GitHub release (latest by date)](https://img.shields.io/github/v/release/GrandMoff100/HomeassistantAPI?style=for-the-badge)
-![GitHub release (latest by date)](https://img.shields.io/github/downloads/GrandMoff100/HomeassistantAPI/latest/total?style=for-the-badge)
+[![Read the Docs (version)](https://img.shields.io/readthedocs/homeassistantapi?style=for-the-badge)](https://homeassistantapi.readthedocs.io/en/latest/?badge=latest)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/GrandMoff100/HomeassistantAPI?style=for-the-badge)](https://github.com/GrandMoff100/HomeassistantAPI/releases)
 
-![Home AssistantLogo](https://github.com/GrandMoff100/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true)
+[![Home Assistant Logo](https://github.com/GrandMoff100/HomeAssistantAPI/blob/7edb4e6298d37bda19c08b807613c6d351788491/docs/images/homeassistant-logo.png?raw=true)](https://home-assistant.io)
 
 Python Wrapper for Homeassistant's [REST API](https://developers.home-assistant.io/docs/api/rest/)
 

TODO.md

@@ -1,10 +1,20 @@
-# Todo
+# TODOs (A checklist of sorts)
 
-## Features
-- [ ] Add caching to Entity.get_state (to make it fetch state automatically)
+## Code Features
 
-- [X] Create AsyncClient for integration in async applications and libraries
+- [ ] Add Testing Suite/Workflow the runs Home Assistant Core to test library.
+- [X] Clean up Model `repr` methods with disabling model field `repr`s.
 
-- [X] Add if statements to all Client methods that call malformed_id and raise MalformedInputError if true.
+## Code Bugs
 
-## Documentation
+None yet?
+
+## Maintenance
+
+- [ ] Fix workflows to only run when python paths are modified.
+
+## Documentation
+
+- [ ] Add runnable Code Examples.
+- [ ] Document project scripts.
+- [ ] Document branch naming scheme (i.e. `feature/<some_feature>`, `maintenance/<stuff>`, `bug/<bug-title>`, `docs/<feature/version>`)

docs/development.rst → docs/CONTRIBUTING.rst

@@ -1,7 +1,7 @@
 .. _development_page:
 
 *****************
-Development
+Contributing
 *****************
 
 This page is where development related things are.

homeassistant_api/_async/asyncclient.py

@@ -1,16 +1,14 @@
 """Module for interacting with Home Assistant asyncronously."""
 import asyncio
-from datetime import datetime
 from os.path import join
 from typing import Any, AsyncGenerator, Dict, List, Optional, Tuple, Union, cast
 
 import aiohttp
 from aiohttp_client_cache import CachedSession
 
-from ..const import DATE_FMT
 from ..errors import APIConfigurationError, MalformedDataError, RequestError
 from ..mixins import JsonProcessingMixin
-from ..models import Domain, Event, History, State
+from ..models import Domain, Event, History, LogbookEntry, State
 from ..processing import Processing
 from ..rawapi import RawWrapper
 from .models import AsyncEntity, AsyncGroup
@@ -85,28 +83,14 @@ async def async_api_config(self) -> Dict[str, Any]:
 
     async def async_logbook_entries(
         self,
-        filter_entity: AsyncEntity = None,
-        start_timestamp: Union[str, datetime] = None,  # Defaults to 1 day before
-        end_timestamp: Union[str, datetime] = None,
-    ) -> Tuple[Dict[str, Any], ...]:
+        *args,
+        **kwargs,
+    ) -> AsyncGenerator[LogbookEntry, None]:
         """Returns a list of logbook entries from homeassistant."""
-        params: Dict[str, str] = {}
-        if filter_entity is not None:
-            params.update(entity=filter_entity.entity_id)
-        if end_timestamp is not None:
-            if isinstance(end_timestamp, datetime):
-                end_timestamp = end_timestamp.strftime(DATE_FMT)
-            params.update(end_time=end_timestamp)
-        if start_timestamp is not None:
-            if isinstance(start_timestamp, datetime):
-                formatted_timestamp = start_timestamp.strftime(DATE_FMT)
-            url = join("logbook", formatted_timestamp)
-        else:
-            url = "logbook"
-        return cast(
-            Tuple[Dict[str, Any], ...],
-            await self.async_request(url, params=params),
-        )
+        params, url = self.prepare_get_logbook_entry_params(*args, **kwargs)
+        data = await self.async_request(url, params=params)
+        for entry in data:
+            yield LogbookEntry.parse_obj(entry)
 
     async def async_get_entity_histories(
         self,

homeassistant_api/_async/models/entity.py

@@ -2,6 +2,8 @@
 from os.path import join
 from typing import TYPE_CHECKING, Any, Dict, Optional, cast
 
+from pydantic import Field
+
 from ...models import BaseModel, History, State
 
 if TYPE_CHECKING:
@@ -12,7 +14,7 @@ class AsyncGroup(BaseModel):
     """Represents the groups that entities belong to"""
 
     group_id: str
-    client: "Client"
+    client: "Client" = Field(exclude=True, repr=False)
     entities: Dict[str, "AsyncEntity"] = {}
 
     def add_entity(self, entity_slug: str, state: State) -> None:

homeassistant_api/_async/models/events.py

@@ -1,6 +1,8 @@
 """Event Model File"""
 from typing import TYPE_CHECKING, Dict, cast
 
+from pydantic import Field
+
 from ...models import BaseModel
 
 if TYPE_CHECKING:
@@ -17,7 +19,7 @@ class AsyncEvent(BaseModel):
 
     event_type: str
     listener_count: int
-    client: "Client"
+    client: "Client" = Field(exclude=True, repr=False)
 
     async def async_fire(self, **event_data) -> str:
         """Fires the event type in homeassistant. Ex. `on_startup`"""

homeassistant_api/mixins.py

@@ -21,7 +21,7 @@ def process_services_json(self, json: Dict[str, Any]) -> Domain:
     @staticmethod
     def process_state_json(json: Dict[str, Any]) -> State:
         """Constructs State model from json data"""
-        return State(**json)
+        return State.parse_obj(json)
 
     def process_event_json(self, json: Dict[str, Any]) -> Event:
         """Constructs Event model from json data"""
@@ -43,11 +43,11 @@ async def async_process_services_json(
     @staticmethod
     async def async_process_state_json(json: Dict[str, Any]) -> State:
         """Constructs State model from json data"""
-        return State(**json)
+        return State.parse_obj(json)
 
     async def async_process_event_json(
         self,
         json: Dict[str, Any],
     ) -> AsyncEvent:
-        """Constructs Event model from json data"""
+        """Constructs Event model from json data."""
         return AsyncEvent(**json, client=self)

homeassistant_api/models/__init__.py

@@ -4,4 +4,5 @@
 from .entity import Entity, Group
 from .events import Event
 from .history import History
+from .logbook import LogbookEntry
 from .states import State

homeassistant_api/models/domains.py

@@ -1,6 +1,8 @@
 """File for Service and Domain data models"""
 from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
 
+from pydantic import Field
+
 from .base import BaseModel
 from .states import State
 
@@ -12,7 +14,7 @@ class Domain(BaseModel):
     """Model representing the domain that services belong to."""
 
     domain_id: str
-    client: "Client"
+    client: "Client" = Field(exclude=True, repr=False)
     services: Dict[str, "Service"] = {}
 
     def add_service(self, service_id: str, **data) -> None:

homeassistant_api/models/entity.py

@@ -3,6 +3,8 @@
 from os.path import join
 from typing import TYPE_CHECKING, Any, Dict, Optional, cast
 
+from pydantic import Field
+
 from .base import BaseModel
 from .history import History
 from .states import State
@@ -15,7 +17,7 @@ class Group(BaseModel):
     """Represents the groups that entities belong to."""
 
     group_id: str
-    client: "Client"
+    client: "Client" = Field(exclude=True, repr=False)
     entities: Dict[str, "Entity"] = {}
 
     def add_entity(self, entity_slug: str, state: State) -> None:

homeassistant_api/models/events.py

@@ -2,6 +2,8 @@
 
 from typing import TYPE_CHECKING, Dict, cast
 
+from pydantic import Field
+
 from .base import BaseModel
 
 if TYPE_CHECKING:
@@ -18,7 +20,7 @@ class Event(BaseModel):
 
     event_type: str
     listener_count: int
-    client: "Client"
+    client: "Client" = Field(exclude=True, repr=False)
 
     def fire(self, **event_data) -> str:
         """Fires the corresponding event in Home Assistant."""

homeassistant_api/models/logbook.py

@@ -0,0 +1,17 @@
+"""Module for the Logbook Entry model."""
+from datetime import datetime
+from typing import Optional
+
+from .base import BaseModel
+
+
+class LogbookEntry(BaseModel):
+    """Model representing"""
+
+    when: datetime
+    name: str
+    entity_id: str
+    state: Optional[str] = None
+    domain: Optional[str] = None
+    context_id: Optional[str] = None
+    icon: Optional[str] = None

homeassistant_api/processing.py

@@ -2,7 +2,7 @@
 
 import inspect
 import json
-from typing import Callable, Dict, Tuple, Union
+from typing import Callable, ClassVar, Dict, Tuple, Union
 
 import simplejson
 from aiohttp import ClientResponse
@@ -26,7 +26,7 @@ class Processing(BaseModel):
     """Uses to processor functions to convert json data into common python data types."""
 
     response: Union[Response, CachedResponse, ClientResponse, AsyncCachedResponse]
-    _processors: Dict[str, Tuple[Callable, ...]] = {}
+    _processors: ClassVar[Dict[str, Tuple[Callable, ...]]] = {}
 
     @staticmethod
     def processor(mimetype: str):

homeassistant_api/rawapi.py

@@ -2,7 +2,7 @@
 
 import os
 from datetime import datetime
-from typing import Dict, Optional, Tuple
+from typing import Dict, Optional, Tuple, Union
 
 from .const import DATE_FMT
 from .errors import MalformedInputError
@@ -26,8 +26,6 @@ def __init__(
     ) -> None:
         if global_request_kwargs is None:
             global_request_kwargs = {}
-        if not self.api_url.endswith("/"):
-            self.api_url += "/"
         if cache_backend is None:
             cache_backend = "memory"
         if cache_expire_after is None:
@@ -39,6 +37,9 @@ def __init__(
         self.cache_backend = cache_backend
         self.cache_expire_after = cache_expire_after
 
+        if not api_url.endswith("/"):
+            self.api_url += "/"
+
     def endpoint(self, path: str) -> str:
         """Joins the api base url with a local path to an absolute url"""
         return os.path.join(self.api_url, path)
@@ -132,3 +133,27 @@ def prepare_get_entity_histories_params(
         else:
             url = "history/period"
         return params, url
+
+    @staticmethod
+    def prepare_get_logbook_entry_params(
+        filter_entity: Optional[Entity] = None,
+        start_timestamp: Optional[
+            Union[str, datetime]
+        ] = None,  # Defaults to 1 day before
+        end_timestamp: Optional[Union[str, datetime]] = None,
+    ) -> Tuple[Dict[str, str], str]:
+        """Prepares the query string and url path for retrieving logbook entries."""
+        params: Dict[str, str] = {}
+        if filter_entity is not None:
+            params.update(entity=filter_entity.entity_id)
+        if end_timestamp is not None:
+            if isinstance(end_timestamp, datetime):
+                end_timestamp = end_timestamp.strftime(DATE_FMT)
+            params.update(end_time=end_timestamp)
+        if start_timestamp is not None:
+            if isinstance(start_timestamp, datetime):
+                formatted_timestamp = start_timestamp.strftime(DATE_FMT)
+            url = os.path.join("logbook", formatted_timestamp)
+        else:
+            url = "logbook"
+        return params, url