httpstate 0.0.13__tar.gz → 0.0.15__tar.gz

{httpstate-0.0.13 → httpstate-0.0.15}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: httpstate
-Version: 0.0.13
-Summary: HTTP State, httpstate.com
-Author-email: "Alex Morales, HTTP State" <alex@httpstate.com>
+Version: 0.0.15
+Summary: HTTPState, httpstate.com
+Author-email: "Alex Morales, HTTPState" <alex@httpstate.com>
 License-Expression: AGPL-3.0
 License-File: LICENSE
 Keywords: httpstate
@@ -28,7 +28,7 @@ Import
 import httpstate
 ```
 
-Pick any valid UUID v4. You can [generate one here](https://www.uuidgenerator.net/version4).
+Pick any valid UUID v4. You can [generate one here](https://uuid.httpstate.com).
 
 We'll use `45fb3654-0e92-44da-aa21-ca409c6bdab3` or `45fb36540e9244daaa21ca409c6bdab3` (without dashes).
 
@@ -44,7 +44,7 @@ and retrieve it with
 data = httpstate.get('45fb36540e9244daaa21ca409c6bdab3')
 ```
 
-You can also get real-time updates
+You can also get realtime updates
 
 ```python
 hs = httpstate.HttpState('45fb36540e9244daaa21ca409c6bdab3')
@@ -58,40 +58,61 @@ That's it! 🐙
 
 ### Functions
 
-- `get(uuid)`  
-  Get state of UUIDv4.
+- `get(uuid)`
+  Get state of UUIDv4. Returns `None|str`.
 
-- `read(uuid)`  
+- `message.unpack(bytes)`
+  Unpack binary WebSocket message into `MessageType(uuid, timestamp, type, value)`.
+
+- `post(uuid, data=None)`
+  Alias for `set`. Returns `None|int`.
+
+- `put(uuid, data=None)`
+  Alias for `set`. Returns `None|int`.
+
+- `read(uuid)`
   Alias for `get`.
 
-- `set(uuid, data)`  
-  Set state of UUIDv4.
+- `set(uuid, data=None)`
+  Set state of UUIDv4. Returns `None|int`. If `data` is `None`, defaults to `''`.
 
-- `write(uuid, data)`  
+- `write(uuid, data=None)`
   Alias for `set`.
 
 ### HttpState Class
 
-- `HttpState(uuid)`  
+- `HttpState(uuid)`
   Create a reactive state instance of UUIDv4.
+- `<HttpState>.data`
+  Property with the most up-to-date state value.
 
 <br>
 
-- `<HttpState>.get()`  
-  Get state.
-- `<HttpState>.read()`  
+- `<HttpState>.get()`
+  Get state. Returns `None|str`.
+- `<HttpState>.post(data=None)`
+  Alias for `set`.
+- `<HttpState>.put(data=None)`
+  Alias for `set`.
+- `<HttpState>.read()`
   Alias for `get`.
-- `<HttpState>.set(data)`  
-  Set state.
-- `<HttpState>.write(data)`  
+- `<HttpState>.set(data=None)`
+  Set state. Returns `None|int`. If `data` is `None`, defaults to `''`.
+- `<HttpState>.write(data=None)`
   Alias for `set`.
 
 <br>
 
-- `<HttpState>.off(type, callback)`  
-  Unsubscribe from real-time updates.
-- `<HttpState>.on(type, callback)`  
-  Subscribe to real-time updates (type = `change`).
+- `<HttpState>.off(type, callback)`
+  Unsubscribe from realtime updates.
+- `<HttpState>.on(type, callback)`
+  Subscribe to realtime updates.
+  - `change`: fired when state data changes. Callback receives current data as argument.
+
+<br>
+
+- `<HttpState>.delete()`
+  Cleanup and delete the instance.
 
 ---
 

{httpstate-0.0.13 → httpstate-0.0.15}/README.md

@@ -14,7 +14,7 @@ Import
 import httpstate
 ```
 
-Pick any valid UUID v4. You can [generate one here](https://www.uuidgenerator.net/version4).
+Pick any valid UUID v4. You can [generate one here](https://uuid.httpstate.com).
 
 We'll use `45fb3654-0e92-44da-aa21-ca409c6bdab3` or `45fb36540e9244daaa21ca409c6bdab3` (without dashes).
 
@@ -30,7 +30,7 @@ and retrieve it with
 data = httpstate.get('45fb36540e9244daaa21ca409c6bdab3')
 ```
 
-You can also get real-time updates
+You can also get realtime updates
 
 ```python
 hs = httpstate.HttpState('45fb36540e9244daaa21ca409c6bdab3')
@@ -44,40 +44,61 @@ That's it! 🐙
 
 ### Functions
 
-- `get(uuid)`  
-  Get state of UUIDv4.
+- `get(uuid)`
+  Get state of UUIDv4. Returns `None|str`.
 
-- `read(uuid)`  
+- `message.unpack(bytes)`
+  Unpack binary WebSocket message into `MessageType(uuid, timestamp, type, value)`.
+
+- `post(uuid, data=None)`
+  Alias for `set`. Returns `None|int`.
+
+- `put(uuid, data=None)`
+  Alias for `set`. Returns `None|int`.
+
+- `read(uuid)`
   Alias for `get`.
 
-- `set(uuid, data)`  
-  Set state of UUIDv4.
+- `set(uuid, data=None)`
+  Set state of UUIDv4. Returns `None|int`. If `data` is `None`, defaults to `''`.
 
-- `write(uuid, data)`  
+- `write(uuid, data=None)`
   Alias for `set`.
 
 ### HttpState Class
 
-- `HttpState(uuid)`  
+- `HttpState(uuid)`
   Create a reactive state instance of UUIDv4.
+- `<HttpState>.data`
+  Property with the most up-to-date state value.
 
 <br>
 
-- `<HttpState>.get()`  
-  Get state.
-- `<HttpState>.read()`  
+- `<HttpState>.get()`
+  Get state. Returns `None|str`.
+- `<HttpState>.post(data=None)`
+  Alias for `set`.
+- `<HttpState>.put(data=None)`
+  Alias for `set`.
+- `<HttpState>.read()`
   Alias for `get`.
-- `<HttpState>.set(data)`  
-  Set state.
-- `<HttpState>.write(data)`  
+- `<HttpState>.set(data=None)`
+  Set state. Returns `None|int`. If `data` is `None`, defaults to `''`.
+- `<HttpState>.write(data=None)`
   Alias for `set`.
 
 <br>
 
-- `<HttpState>.off(type, callback)`  
-  Unsubscribe from real-time updates.
-- `<HttpState>.on(type, callback)`  
-  Subscribe to real-time updates (type = `change`).
+- `<HttpState>.off(type, callback)`
+  Unsubscribe from realtime updates.
+- `<HttpState>.on(type, callback)`
+  Subscribe to realtime updates.
+  - `change`: fired when state data changes. Callback receives current data as argument.
+
+<br>
+
+- `<HttpState>.delete()`
+  Cleanup and delete the instance.
 
 ---
 

{httpstate-0.0.13 → httpstate-0.0.15}/pyproject.toml

@@ -3,20 +3,20 @@ build-backend = "hatchling.build"
 requires = ["hatchling >= 1.26"]
 
 [project]
-authors = [{ email="alex@httpstate.com", name="Alex Morales, HTTP State" }]
+authors = [{ email="alex@httpstate.com", name="Alex Morales, HTTPState" }]
 classifiers = [
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3"
 ]
 dependencies = ["websockets>=16.0"]
-description = "HTTP State, httpstate.com"
+description = "HTTPState, httpstate.com"
 keywords = ["httpstate"]
 license = "AGPL-3.0"
 license-files = ["LICEN[CS]E*"]
 name = "httpstate"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.0.13"
+version = "0.0.15"
 
 [project.url]
 Homepage = "https://httpstate.com"

{httpstate-0.0.13 → httpstate-0.0.15}/src/httpstate/__init__.py

@@ -1,4 +1,4 @@
-# HTTP State, https://httpstate.com/
+# HTTPState, https://httpstate.com/
 # Copyright (C) Alex Morales, 2026
 
 # Unless otherwise stated in particular files or directories, this software is free software.
@@ -8,6 +8,9 @@
 
 from .httpstate import(
   get,
+  message,
+  post,
+  put,
   read,
   set,
   write,
@@ -16,6 +19,9 @@ from .httpstate import(
 
 __all__ = [
   'get',
+  'message',
+  'post',
+  'put',
   'read',
   'set',
   'write',

{httpstate-0.0.13 → httpstate-0.0.15}/src/httpstate/httpstate.py

@@ -1,4 +1,4 @@
-# HTTP State, https://httpstate.com/
+# HTTPState, https://httpstate.com/
 # Copyright (C) Alex Morales, 2026
 
 # Unless otherwise stated in particular files or directories, this software is free software.
@@ -7,6 +7,7 @@
 # version 3 of the License, or (at your option) any later version.
 
 import asyncio
+import struct
 import threading
 import urllib.error
 import urllib.request
@@ -26,11 +27,41 @@ def get(uuid:str) -> None|str:
   except Exception:
     return None
 
+class MessageType:
+  def __init__(self, uuid:str, timestamp:int, type:int, value:bytes) -> None:
+    self.uuid:str = uuid
+    self.timestamp:int = timestamp
+    self.type:int = type
+    self.value:bytes = value
+
+class Message:
+  @staticmethod
+  def unpack(b:bytes) -> MessageType:
+    length:int = b[0]
+
+    return MessageType(
+      uuid=b[1:1+length].decode('utf-8'),
+      timestamp=struct.unpack_from('>Q', b, 1+length)[0],
+      type=b[1+length+8],
+      value=b[1+length+9:],
+    )
+
+message:type = Message
+
+def post(uuid:str, data:None|str = None) -> None|int:
+  return set(uuid, data)
+
+def put(uuid:str, data:None|str = None) -> None|int:
+  return set(uuid, data)
+
 def read(uuid:str) -> None|str:
   return get(uuid)
 
-def set(uuid:str, data:str) -> None|int:
-  req = urllib.request.Request(
+def set(uuid:str, data:None|str = None) -> None|int:
+  if(data is None):
+    data = ''
+
+  req:urllib.request.Request = urllib.request.Request(
     f'https://httpstate.com/{uuid}',
     data=data.encode('utf-8'),
     headers={ 'Content-Type':'text/plain;charset=UTF-8' },
@@ -45,15 +76,16 @@ def set(uuid:str, data:str) -> None|int:
   except Exception:
     return None
 
-def write(uuid:str, data:str) -> None|int:
+def write(uuid:str, data:None|str = None) -> None|int:
   return set(uuid, data)
 
-# HTTP State
+# HTTPState
 class HttpState:
-  def __init__(self, uuid:str):
+  def __init__(self, uuid:str) -> None:
     self.data:None|str = None
     self.el:None|asyncio.AbstractEventLoop = None
     self.et:Dict[str, List[Callable[[None|str], None]]] = {}
+    self.lock:threading.Lock = threading.Lock()
     self.uuid:str = uuid
     self.ws:None|websockets.WebSocketClientProtocol = None
 
@@ -67,8 +99,8 @@ class HttpState:
       target=lambda : asyncio.run(self._ws())
     ).start()
   
-  def _el(self):
-    self.el = asyncio.new_event_loop()
+  def _el(self) -> None:
+    self.el:asyncio.AbstractEventLoop = asyncio.new_event_loop()
     
     asyncio.set_event_loop(self.el)
     
@@ -76,29 +108,29 @@ class HttpState:
 
     self.el.run_forever()
 
-  async def _ws(self):
-    self.ws = await websockets.connect(f"wss://httpstate.com/{self.uuid}")
+  async def _ws(self) -> None:
+    self.ws:websockets.WebSocketClientProtocol = await websockets.connect(f"wss://httpstate.com/{self.uuid}")
 
     await self.ws.send(f'{{"open":"{self.uuid}"}}')
     self.emit('open')
 
-    async def data():
+    async def data() -> None:
       async for data in self.ws:
-        data = data.decode()
+        data:MessageType = message.unpack(data)
 
         if(
               data
-          and len(data) > 32
-          and data[:32] == self.uuid
-          and data[45] == '1'
+          and data.uuid == self.uuid
+          and data.type == 1
         ):
-          self.data = data[46:]
+          with self.lock:
+            self.data:None|str = data.value.decode()
 
           self.emit('change', self.data)
     
     asyncio.create_task(data())
 
-    async def interval():
+    async def interval() -> None:
       while True:
         try:
           await self.ws.ping()
@@ -111,10 +143,10 @@ class HttpState:
     
     await asyncio.Event().wait()
   
-  def destroy(self):
+  def delete(self) -> None:
     pass
 
-  def emit(self, type:str, data:None|str = None):
+  def emit(self, type:str, data:None|str = None) -> "HttpState":
     for callback in self.et.get(type, []):
       if(data is None):
         callback()
@@ -124,16 +156,18 @@ class HttpState:
     return self
 
   def get(self) -> None|str:
-    data = get(self.uuid)
+    data:None|str = get(self.uuid)
 
-    if(data != self.data):
-      self.el.call_soon_threadsafe(lambda : self.emit('change', self.data))
+    with self.lock:
+      if(data != self.data):
+        if self.el is not None:
+          self.el.call_soon_threadsafe(lambda : self.emit('change', self.data))
 
-    self.data = data
+      self.data = data
 
     return self.data
 
-  def off(self, type:str, callback:Callable[[None|str], None]):
+  def off(self, type:str, callback:Callable[[None|str], None]) -> "HttpState":
     if type in self.et:
       try:
         self.et[type].remove(callback)
@@ -145,19 +179,25 @@ class HttpState:
 
     return self
 
-  def on(self, type:str, callback:Callable[[None|str], None]):
+  def on(self, type:str, callback:Callable[[None|str], None]) -> "HttpState":
     if type not in self.et:
       self.et[type] = []
 
     self.et[type].append(callback)
 
     return self
+  
+  def post(self, data:None|str = None) -> None|int:
+    return self.set(data)
+  
+  def put(self, data:None|str = None) -> None|int:
+    return self.set(data)
 
   def read(self) -> None|str:
     return self.get()
 
-  def set(self, data:str) -> None|int:
+  def set(self, data:None|str = None) -> None|int:
     return set(self.uuid, data)
 
-  def write(self, data:str) -> None|int:
+  def write(self, data:None|str = None) -> None|int:
     return self.set(data)