qsql 1.0.2.2__py2.py3-none-any.whl

qsql-1.0.2.2.dist-info/METADATA

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: qsql
+Version: 1.0.2.2
+Summary: Parses queries from an sql file, and turns them into callable f-strings. Also a file cache decorator for slow queries and multi-session permanence, supports async functions.
+Author-email: Charles Marks <charlesmarksco@gmail.com>
+Description-Content-Type: text/markdown
+Classifier: License :: OSI Approved :: MIT License
+License-File: LICENSE
+Requires-Dist: orjson
+Project-URL: Home, https://github.com/CircuitCM/pyquicksql
+
+
+
+# PyQuickSQL
+For a more thorough explanation see [example.md](https://github.com/CircuitCM/pyquicksql/blob/main/example.md)  
+To install: `pip install qsql`  
+### How to use the query loader:
+```python
+import quicksql as qq
+queries = qq.LoadSQL('path/to/queries.sql')
+```
+Printing the queries should give you something like this:
+```text
+LoadSQL('path/to/queries.sql')
+Query Name: examplequery_1, Params: order_avg, num_orders
+Query Name: examplequery_2, Params: sdate, edate, product_id
+```
+These are callable objects that return the string given the non-optional **params.  
+They are equivalent to an f-string + a lambda but loaded from an sql file and stored in the LoadSQL object.  
+`print(str(queries))` will give you the raw SQL string.  
+  
+How to use them:
+```python
+print(queries.examplequery_2(
+    product_id=10,
+    sdate='1-10-2022',
+    edate=qq.NoStr("DATE'4-11-2023'"),
+    something_not_a_param='test'))
+```
+```text
+Unused variables: something_not_a_param in query examplequery_2
+```
+Above will be printed as a warning with invalid inclusions, no non-verbose option yet.
+```sql
+SELECT
+  c.CustomerName,
+  o.OrderDate,
+  o.Status,
+  (SELECT SUM(od.Quantity * od.UnitPrice) FROM OrderDetails od WHERE od.OrderID = o.OrderID) AS TotalValue
+FROM
+  Customers c
+INNER JOIN Orders o ON c.CustomerID = o.CustomerID
+WHERE
+  o.OrderDate BETWEEN '1-10-2022' AND DATE'4-11-2023'
+  AND EXISTS (SELECT 1 FROM OrderDetails od WHERE od.OrderID = o.OrderID AND od.ProductID = 10)
+ORDER BY
+  TotalValue DESC;
+```
+
+### How to use the file cache:
+This is very similar to functool's `cache`, with the main difference being that `@qq.file_cache` caches the asset to memory
+and to your system's default temporary directory. If the memory cache ever fails (eg a restarted kernel) it will load the asset from it's pickled file.
+```python
+from random import randint
+import quicksql as qq
+@qq.file_cache()
+def test_mem(size:int):
+    return [randint(0,10) for _ in range(size)]
+
+print(test_mem(8))
+```
+`[10, 3, 4, 9, 2, 2, 4, 2]`
+```python
+print(test_mem(8))
+```
+`[10, 3, 4, 9, 2, 2, 4, 2]`
+
+To clear the cache: `qq.clear_cache()`
+
+For more examples and how to configure see [example.ipynb](https://github.com/CircuitCM/pyquicksql/blob/main/example.ipynb)
+

qsql-1.0.2.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+quicksql/__init__.py,sha256=X_D71NOyiKNGcpBskCWvIDQlF8-gAGhs-n9_dIRL5bE,374
+quicksql/__init__.pyi,sha256=aSP6YBmEPuqXttuqPz4bxUboPS1jzKnEItyo2SkKdCo,1356
+quicksql/_quicksql.py,sha256=FdnfluTL2fAhZXcyYRsVpGNL62mwIJSpj2XlKWML764,7586
+quicksql/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qsql-1.0.2.2.dist-info/licenses/LICENSE,sha256=OeyQ5X2phWTZ63Z3P4zUTrh0z_bHbfsQdkWThs2juu4,1091
+qsql-1.0.2.2.dist-info/WHEEL,sha256=BXjIu84EnBiZ4HkNUBN93Hamt5EPQMQ6VkF7-VZ_Pu0,100
+qsql-1.0.2.2.dist-info/METADATA,sha256=h6lIokbjc_McPymhvh3vW_FYhslLVsGUN_6bXGlFMew,2732
+qsql-1.0.2.2.dist-info/RECORD,,

qsql-1.0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: flit 3.11.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

qsql-1.0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Charles Marks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quicksql/__init__.py

@@ -0,0 +1,7 @@
+"""Parses queries from an sql file, and turns them into callable f-strings. Also a file cache decorator for slow queries and multi-session permanence, supports async functions."""
+
+__version__ = '1.0.2.2'
+
+from ._quicksql import file_cache,test_cache,Query,LoadSQL,clear_cache,NoStr
+
+__all__ = ["file_cache", "test_cache", "Query", "LoadSQL", "clear_cache", "NoStr"]

quicksql/__init__.pyi

@@ -0,0 +1,62 @@
+
+
+
+def file_cache(use_mem_cache=..., threadsafe=...): # -> Callable[..., Callable[..., CoroutineType[Any, Any, Any | _NA]] | Callable[..., Any]]:
+    
+    ...
+
+def clear_cache(clr_mem=..., clr_file=...):# -> None:
+    ...
+
+@file_cache()
+def test_cache(*args, **kwargs): # -> tuple[tuple[Any, ...], dict[str, Any]]:
+    ...
+
+class NoStr:
+    __slots__ = ...
+    def __init__(self, string: str) -> None:
+        ...
+    
+    def __str__(self) -> str:
+        ...
+    
+    def __repr__(self): # -> str:
+        ...
+    
+
+
+class Query:
+    
+    def __init__(self, name, query) -> None:
+        
+        ...
+    
+    def __call__(self, **kwargs): # -> Any:
+        ...
+    
+    @cache
+    def __str__(self) -> str:
+        ...
+    
+
+
+class LoadSQL:
+    
+    def __init__(self, path) -> None:
+        
+        ...
+    
+    @cache
+    def __str__(self) -> str:
+        ...
+    
+    @cache
+    def __repr__(self): # -> str:
+        ...
+
+
+from ._quicksql import LoadSQL, NoStr, Query, clear_cache, file_cache, test_cache
+
+"""Parses queries from an sql file, and turns them into callable f-strings. Also a file cache decorator for slow queries and multi-session permanence, supports async functions."""
+__version__ = ...
+__all__ = ["file_cache", "test_cache", "Query", "LoadSQL", "clear_cache", "NoStr"]

quicksql/_quicksql.py

@@ -0,0 +1,215 @@
+import uuid as id
+import pickle as pkl
+import os 
+from functools import cache
+import re
+import copy
+import asyncio as aio
+import hashlib as hl
+import orjson as js
+
+_mem_cache = {}
+cache_dir = os.environ.get('QQ_CACHE_DIR', None)
+if cache_dir is None:
+    import tempfile
+    cache_dir=os.path.join(tempfile.gettempdir(),'qqcache')
+os.makedirs(cache_dir, exist_ok=True)
+
+_FQS = re.compile(r"--\s*name\s*:\s*")
+_FNAM = re.compile(r"\W")
+_VIN = re.compile(r"(?<!:):\w+")
+_alljopts=js.OPT_SERIALIZE_DATACLASS|js.OPT_SERIALIZE_NUMPY|js.OPT_SERIALIZE_UUID|js.OPT_NAIVE_UTC|js.OPT_NON_STR_KEYS
+
+
+
+class _NA(object): #so None is still valid
+    pass
+
+def _lf(name):
+    try:
+        with open(name, 'rb') as file:
+            result = pkl.load(file)
+        return result
+    except FileNotFoundError:
+        return _NA()
+
+def _sf(name,result):
+    with open(name, 'wb') as file:
+        pkl.dump(result, file)
+
+
+def _make_key(*args,**kwargs):
+    return hl.blake2b(js.dumps((args, kwargs),option=_alljopts),usedforsecurity=False).hexdigest()
+
+
+def file_cache(use_mem_cache=True,threadsafe=True):
+    """
+    :param use_mem_cache: If true, will cache in memory as well as file
+    :param threadsafe: If false, and your function is async, will deepcopy the result in a separate thread to not block, for small assets false is probably a bit slower.
+    :return: A decorator that will cache the result of a function in a file
+    """
+    def wrapper1(func):
+        isco,iscofun= aio.iscoroutinefunction(func), aio.iscoroutine(func)
+        if isco or iscofun:
+            async def wrapper(*args, **kwargs):
+                nargs=args+(func.__name__,)
+                key=_make_key(*nargs,**kwargs)
+                file_name = os.path.join(cache_dir,f"{key}.pkl")
+                if use_mem_cache:
+                    val = _mem_cache.get(key, _NA())
+                    incache = type(val) is not _NA
+                    if incache:
+                        if threadsafe:
+                            return copy.deepcopy(val)
+                        else:
+                            return await aio.get_running_loop().run_in_executor(None, copy.deepcopy, val)
+
+                result = await aio.get_running_loop().run_in_executor(None, _lf, file_name)
+                if type(result) is _NA:
+                    if isco:
+                        result = await func(*args, **kwargs)
+                    else:
+                        result = await func
+                    #File cache is always a backup so restarting an interpreter is safe, Need to explicitly clear cache if the remote dataset changes
+                    await aio.get_running_loop().run_in_executor(None,_sf, file_name, result)
+                if use_mem_cache:
+                    _mem_cache[key] = result
+                return result
+        else:
+            def wrapper(*args, **kwargs):
+                nargs=args+(func.__name__,)
+                key = _make_key(*nargs, **kwargs)
+                file_name = os.path.join(cache_dir,f"{key}.pkl")
+                if use_mem_cache:
+                    val = _mem_cache.get(key, _NA())
+                    incache = type(val) is not _NA
+                    if incache:
+                        return copy.deepcopy(val)
+                try:
+                    with open(file_name, 'rb') as file:
+                        result = pkl.load(file)
+                except FileNotFoundError:
+                    result = func(*args, **kwargs)
+                    #File cache is always a backup so restarting an interpreter is safe, Need to explicitly clear cache if the remote dataset changes
+                    with open(file_name, 'wb') as file:
+                        pkl.dump(result, file)
+                if use_mem_cache:
+                    _mem_cache[key] = result
+                return result
+
+        return wrapper
+    return wrapper1
+
+
+def clear_cache(clr_mem=True, clr_file=True):
+    """
+    :param clr_mem: If true, will clear memory cache
+    :param clr_file: If true, will clear file cache
+    :return: None
+    """
+
+    if clr_mem:
+        _mem_cache.clear()
+        print("Memory cache cleared.")
+    if clr_file:
+        for file in os.listdir(cache_dir):
+            os.remove(os.path.join(cache_dir, file))
+        print("File cache cleared.")
+
+
+#need to add closed parentheses for it to work idk why, maybe an optional arg thing.
+@file_cache()
+def test_cache(*args, **kwargs):
+    return args, kwargs
+
+
+class NoStr:
+
+    __slots__=('string',)
+
+    def __init__(self,string:str):
+        self.string=string
+
+    def __str__(self):
+        return self.string
+
+    def __repr__(self):
+        return self.string
+
+
+class Query:
+    """
+    This is a convenience wrapper to generate SQL queries with named variables. It is basically the same as a lambda **g: f-string
+    but it takes the SQL variable notation so it can parse a query from a .sql file.
+    """
+
+    def __init__(self, name, query):
+        """
+        :param name: Name of query
+        :param query: SQL query with :var_name variables
+        """
+
+        self.name = name
+        self.query = query
+        self._rvrs=list({vr for vr in _VIN.findall(query)}) #to remove duplicate keys
+        self.vars = [v[1:] for v in self._rvrs]
+
+    def __call__(self, **kwargs):
+        #Can't use python string methods here as it might conflict with SQL syntax
+        oq=self.query
+        for v in zip(self._rvrs, self.vars):
+            rp=kwargs.get(v[1],None)
+            if rp is None:
+                raise ValueError(f"Missing value for variable {v[1]}")
+            oq=oq.replace(v[0], str(rp) if type(rp) is not str else f"'{rp}'")
+        chk_nkg=kwargs.keys()-self.vars
+        if len(chk_nkg)>0:
+            print(f"Unused variables: {', '.join(chk_nkg)} in query {self.name}")
+        return oq
+
+    @cache
+    def __str__(self):
+        return f"-- Query:: {self.name}\n{self.query}"
+
+
+
+class LoadSQL:
+    """
+    An object that holds all the named queries from a .sql file.
+    Names are specified with -- name: <name> and queries are separated by the next -- name: or -- :end.
+    """
+
+    def __init__(self, path):
+        """
+        :param path: Path to .sql file
+        """
+        self.path = path
+        end_marker = '-- :end'
+        with open(path, 'r') as file:
+            qf = file.read()
+
+        qdefs = _FQS.split(qf)
+        for qdef in qdefs[1:]:
+            name, query = qdef.split('\n', 1)
+            name = name.strip()
+
+            # Validate that the name is a valid Python identifier
+            if not name.isidentifier():
+                raise ValueError(f"The name '{name}' is not a valid Python identifier.")
+
+            # Truncate the query if end marker is present
+            end_idx = query.rfind(end_marker)
+            if end_idx != -1:
+                query = query[:end_idx]
+
+            setattr(self, name, Query(name, query.rstrip()))
+
+    @cache
+    def __str__(self):
+        _s = '\n\n'
+        return f"Queries from:: {self.path}\n\n{_s.join([str(qr) for nm, qr in self.__dict__.items() if nm != 'path']) if len(self.__dict__) > 1 else 'No queries found.'}"
+
+    @cache
+    def __repr__(self):
+        _s = '\n'
+        return f"LoadSQL({self.path})\n{_s.join([f'Query Name: '+nm+', Params: '+', '.join(qr.vars) for nm, qr in self.__dict__.items() if nm != 'path']) if len(self.__dict__) > 1 else 'No queries found.'}"