119 refactor docs

.github/workflows/checks.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.8", "3.9", "3.10", "3.11", "3.12",]
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/setup-python@v4
         with:
@@ -32,21 +32,26 @@ jobs:
           poetry install --no-root --no-interaction --no-ansi --without docs
       - name: Execute Tests
         run: poetry run task tests
-      - uses: actions/upload-artifact@v3
+      - name: Rename file
+        env:
+          VER: ${{ matrix.python }}
+        run: mv ./coverage.xml ./coverage-$VER.xml
+      - uses: actions/upload-artifact@v4
         with:
-          name: coverage.xml
-          path: coverage.xml
+          name: coverage-${{ matrix.python }}.xml
+          path: coverage-${{ matrix.python }}.xml
       - name: Coveralls
-        uses: coverallsapp/github-action@v2
+        uses: coverallsapp/github-action@v2.3.0
         with:
-          file: coverage.xml
+          coverage-reporter-version: v0.6.14
+          file: coverage-${{ matrix.python }}.xml
   lint:
     name: Code Lint
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.8", "3.9", "3.10", "3.11", "3.12",]
+        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/setup-python@v4
         with:
@@ -75,16 +80,18 @@ jobs:
     steps:
       - uses: actions/checkout@v3
         with:
-          fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
-      - uses: actions/download-artifact@v3
+          fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
+      - uses: actions/download-artifact@v4
         with:
-          name: coverage.xml
-      - name: fix code coverage paths
+          name: coverage-3.12.xml
+      - name: Rename file
+        run: mv ./coverage{-3.12,}.xml
+      - name: Fix code coverage paths
         run: |
           sed -i 's/\/home\/runner\/work\/py-cachify\/py-cachify\//\/github\/workspace\//g' /home/runner/work/py-cachify/py-cachify/coverage.xml
           cat /home/runner/work/py-cachify/py-cachify/coverage.xml
       - name: SonarCloud Scan
         uses: SonarSource/sonarcloud-github-action@master
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Needed to get PR information, if any
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Needed to get PR information, if any
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

.gitignore

@@ -21,7 +21,8 @@ site_build
 venv
 docs.zip
 archive.zip
-
+.zed
+.zed/*
 # vim temporary files
 *~
 .*.sw?
@@ -322,4 +323,3 @@ Control.system-ca-bundle
 # Visual Studio Code #
 .vscode/
 .history
-

README.md

@@ -1,54 +1,90 @@
 # Py-Cachify
 
-[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![PyPI version](https://badge.fury.io/py/py-cachify.svg)](https://badge.fury.io/py/py-cachify)
-[![Documentation Status](https://readthedocs.org/projects/py-cachify/badge/?version=latest)](https://py-cachify.readthedocs.io/en/latest/?badge=latest)
-[![Build Status](https://github.com/EzyGang/py-cachify/actions/workflows/checks.yml/badge.svg)]()
-[![Tests Status](https://github.com/EzyGang/py-cachify/actions/workflows/integration-tests.yml/badge.svg)]()
-[![Coverage Status](https://coveralls.io/repos/github/EzyGang/py-cachify/badge.png?branch=main)](https://coveralls.io/github/EzyGang/py-cachify?branch=main)
-[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=EzyGang_py-cachify&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=EzyGang_py-cachify)
+<p align="center">
+<a href="https://opensource.org/licenses/MIT" target="_blank">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+</a>
+<a href="https://badge.fury.io/py/py-cachify" target="_blank">
+    <img src="https://badge.fury.io/py/py-cachify.svg" alt="PyPI version">
+</a>
+<a href="https://py-cachify.readthedocs.io/en/latest/?badge=latest" target="_blank">
+    <img src="https://readthedocs.org/projects/py-cachify/badge/?version=latest" alt="Documentation Status">
+</a>
+</p>
+<p align="center">
+<a href="https://github.com/EzyGang/py-cachify/actions/workflows/checks.yml/badge.svg" target="_blank">
+    <img src="https://github.com/EzyGang/py-cachify/actions/workflows/checks.yml/badge.svg" alt="Pre-build checks and Tests">
+</a>
+<a href="https://github.com/EzyGang/py-cachify/actions/workflows/integration-tests.yml/badge.svg" target="_blank">
+    <img src="https://github.com/EzyGang/py-cachify/actions/workflows/integration-tests.yml/badge.svg" alt="Tests Status">
+</a>
+<a href="https://coveralls.io/github/EzyGang/py-cachify?branch=main" target="_blank">
+    <img src="https://coveralls.io/repos/github/EzyGang/py-cachify/badge.png?branch=main" alt="Coverage Status">
+</a>
+<a href="https://sonarcloud.io/summary/new_code?id=EzyGang_py-cachify" target="_blank">
+    <img src="https://sonarcloud.io/api/project_badges/measure?project=EzyGang_py-cachify&metric=reliability_rating" alt="Reliability Rating">
+</a>
+</p>
+
+---
+
+**Documentation**: <a href="https://py-cachify.readthedocs.io/latest/" target="_blank">https://py-cachify.readthedocs.io/latest/</a>
+
+**Source Code**: <a href="https://github.com/EzyGang/py-cachify" target="_blank">https://github.com/EzyGang/py-cachify</a>
+
+---
+
+py-cachify is a small library that provides useful cache-based utilities (caching, distributed locks) that are
+enhanced versions of those provided by similar packages.
+
+py-cachify works well in both sync and async environments, has 100% test coverage, is fully type annotated,
+is backend agnostic (you can provide your own client as long as it matches the signature), and supports Python from 3.8 and upward.
 
-py-cachify is a library that provides small but useful cache utilities.
+It offers distributed (cache-based) locks and decorators to lock function executions,
+and also caching utilities and decorators for storing results in the cache.
 
-Some parts were heavily inspired by [douglasfarinelli's python-cachelock](https://github.com/douglasfarinelli/python-cachelock) lib,
-which is sadly no longer maintained.
+The key features are:
 
-py-cachify works well in both sync and async environments, has 100% test coverage, 
-is backend agnostic (you can provide your own client as long as it matches the signature), and supports Python from 3.8 and upward.
+* **Intuitive to write**: Great editor support. When applying decorators your IDE will still be able to autocomplete and highlight inline errors for applied functions.
+* **Fully type annotated**: You don't have to constantly look into the docs. Everything is type annotated and easy to understand out of the box.
+* **Short**: Minimize code duplication. Add just one line of code to implement a cache or lock on your function.
+* **Start simple**: The simplest example adds only a couple of lines of code: initialize a library and use the needed utility.
+* **Backend agnostic**: Use whatever cache-backend you want to use. Py-Cachify is not forcing you into anything.
+* **Test coverage**: Has 100% test coverage and supports Python 3.8+
 
-It offers distributed (cache based) locks and decorators for securing function executions and storing their results in the cache.
+---
 
 ## Table of Contents
 
-- [Documentation](#documentation)
 - [Installation](#installation)
-- [Examples](#examples)
+- [How to use](#how-to-use)
+- [Basic examples](#basic-examples)
 - [Contributing](#contributing)
 - [License](#license)
 
-## Documentation
-
-Detailed documentation can be found at https://py-cachify.readthedocs.io/en/latest/.
-
 ## Installation
-To install:
+
+<!-- termynal -->
 ```bash
-pip install py-cachify
+$ pip install py-cachify
 
-# or if using poetry
-poetry add py-cachify
+---> 100%
+Successfully installed py-cachify
 ```
 
-## Examples
+## How to use
+
+You can read more in-depth tutorials [here](https://py-cachify.readthedocs.io/latest/tutorial/).
 
-To start working with it, you'll have to initialize it using `init_cachify`:
+First, to start working with the library, you will have to initialize it by using the provided `init_cachify` function:
 ```python
 from py_cachify import init_cachify
 
 init_cachify()
 ```
 By default, it will use an in-memory cache.
 
+
 If you want to use Redis:
 ```python
 from py_cachify import init_cachify
@@ -59,26 +95,65 @@ init_cachify(sync_client=from_url(redis_url), async_client=async_from_url(async_
 ```
 Normally you wouldn't have to use both sync and async clients since an application usually works in a single mode i.e. sync/async.
 
-Once initialized you can use everything that the library provides straight up without being worried about managing the cache yourself. 
+Once initialized you can use everything that the library provides straight up without being worried about managing the cache yourself.
+
+❗ If you forgot to call `init_cachify` the `CachifyInitError` will be raised during runtime.
+
+## Basic examples
+
+### Caching
+
+Caching by using `@cached` decorator utilizing the flexibility of a dynamic key:
 
-If you forgot to call `init_cachify` the `CachifyInitError` will be raised during runtime.
 ```python
-from py_cachify import once
+# Cache the result of the following function with dynamic key
+@cached(key='sum_two-{a}-{b}')
+async def sum_two(a: int, b: int) -> int:
+    # Let's put print here to see what was the function called with
+    print(f'Called with {a} {b}')
+    return a + b
+```
+
+Read more about `@cached` [here](https://py-cachify.readthedocs.io/latest/reference/cached/).
 
+### Locking
 
-# Make sure there is just one copy of a function running at a time
-@once(key='long_running_function')
-async def long_running_function() -> str:
-    # Executing long-running operation...
-    pass
+Locking through context manager:
+
+```python
+from py_cachify import lock
+
+# Use it within an asynchronous context
+async with lock('resource_key'):
+    # Your critical section here
+    print('Critical section code')
+
+
+# Use it within a synchronous context
+with lock('resource_key'):
+    # Your critical section here
+    print('Critical section code')
+```
+
+Locking via decorator:
+
+```python
+
+from py_cachify import lock
+
+@lock(key='critical_function_lock-{arg}', nowait=False, timeout=10)
+def critical_function(arg: int) -> None:
+    # critical code
 ```
 
-For more detailed documentation and examples please visit https://py-cachify.readthedocs.io/en/latest/.
+Read more about `lock` [here](https://py-cachify.readthedocs.io/latest/reference/lock/).
+
+For a more detailed tutorial visit [Tutorial](https://py-cachify.readthedocs.io/latest/tutorial/) or [full API reference](https://py-cachify.readthedocs.io/latest/reference).
 
 ## Contributing
 
 If you'd like to contribute, please first discuss the changes using Issues, and then don't hesitate to shoot a PR which will be reviewed shortly.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/EzyGang/py-cachify/blob/main/LICENSE) file for details.