Merge pull request #11 from mdapena/sdist-size-optimization

Optimize sdist Build Size and Improve Documentation

.github/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
+<a href="mailto:dapensoft@gmail.com" target="_blank">dapensoft@gmail.com</a>.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

.github/workflows/deploy-docs.yml

@@ -31,5 +31,5 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install . mkdocs-material mkdocstrings[python] mkdocs-git-revision-date-localized-plugin mkdocs-git-authors-plugin
+      - run: pip install .[docs]
       - run: mkdocs gh-deploy --force

README.md

@@ -28,10 +28,6 @@
     <img src="https://img.shields.io/pypi/pyversions/pyventus?color=blue" alt="Supported Python versions">
 </a>
 
-<a href="https://www.pepy.tech/projects/pyventus" target="_blank">
-    <img src="https://static.pepy.tech/badge/pyventus/month" alt="Last 30 days downloads for the project">
-</a>
-
 <a href="https://github.com/psf/black">
 	<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black">
 </a>
@@ -51,9 +47,8 @@
 
 <p style='text-align: justify;'>
     &emsp;&emsp;Pyventus is a modern and robust Python package for event-driven programming. It offers a comprehensive
-	suite of tools to define, emit, manage, and orchestrate events with ease, using customizable event emitters and
-	flexible responses. With Pyventus, you can easily build scalable, extensible, and loosely-coupled event-driven
-	applications.
+	suite of tools to easily define, emit, and orchestrate events using customizable event emitters and flexible
+	responses. With Pyventus, you can easily build scalable, extensible, and loosely-coupled event-driven applications.
 </p>
 
 ## More than just Events
@@ -105,9 +100,11 @@ guides, and tutorials to effectively leverage all the features and capabilities
 ## Requirements
 
 <p style='text-align: justify;'>
-	&emsp;&emsp;Pyevents <b>only requires Python 3.10+</b> by default, which includes the <code>AsyncIOEventEmitter</code>
-	and the <code>ExecutorEventEmitter</code> with no additional dependencies. However, your requirements may expand 
-	if you opt to use alternative built-in event emitter implementations.
+	&emsp;&emsp;Pyevents <b>only requires Python 3.10+</b> by default, which includes the 
+	<a href="https://mdapena.github.io/pyventus/tutorials/emitters/asyncio" target="_blank"><code>AsyncIOEventEmitter</code></a>
+	and the <a href="https://mdapena.github.io/pyventus/tutorials/emitters/executor" target="_blank"><code>ExecutorEventEmitter</code></a> 
+	with no additional dependencies. However, your requirements may expand if you opt to use  
+	<a href="https://mdapena.github.io/pyventus/getting-started/#optional-dependencies" target="_blank">alternative built-in event emitter implementations</a>.
 </p>
 
 ## Installation
@@ -175,7 +172,8 @@ indicates that the function should be triggered when <code>MyEvent</code> occurs
 
 <li>
 <b>Creating the event emitter instance:</b> We instantiated the <code>AsyncIOEventEmitter</code> class, which acts as 
-the event emitter responsible for dispatching events and invoking the associated event handler callbacks.
+the event emitter responsible for dispatching events and invoking the associated event handler callbacks. It's important 
+to note that the event emitter used can be changed by any of the built-in or custom event emitter implementations.
 </li>
 
 <li>
@@ -378,7 +376,7 @@ Hello, AsyncIOEventEmitter!
 <details markdown="1" class="tip" open>
 <summary>Official <code>FastAPIEventEmitter</code> integration</summary>
 <p style='text-align: justify;'>
-No need for manual implementation! Pyventus now offers an official <b><a href="/pyventus/tutorials/emitters/fastapi">FastAPIEventEmitter</a></b>
+No need for manual implementation! Pyventus now offers an official <b><a href="https://mdapena.github.io/pyventus/tutorials/emitters/fastapi">FastAPIEventEmitter</a></b>
 integration.
 </p>
 </details>

docs/getting-started.md

@@ -64,7 +64,7 @@ pip install pyventus[celery] (1)
 
     > These optional dependencies can be installed as described in their individual documentation. For example:
        ```console
-       install celery[...]
+       pip install celery[...]
        ```
 
 ---
@@ -104,7 +104,7 @@ pip install pyventus[fastapi] (1)
 
     >  These optional dependencies can be installed as described in their individual documentation. For example:
        ```console
-       install fastapi[...]
+       pip install fastapi[...]
        ```
 
 </ul>

docs/index.md

@@ -40,10 +40,6 @@ hide:
     <img src="https://img.shields.io/pypi/pyversions/pyventus?color=blue" alt="Supported Python versions">
 </a>
 
-<a href="https://www.pepy.tech/projects/pyventus" target="_blank">
-    <img src="https://static.pepy.tech/badge/pyventus/month" alt="Last 30 days downloads for the project">
-</a>
-
 <a href="https://github.com/psf/black">
 	<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black">
 </a>
@@ -170,7 +166,8 @@ indicates that the function should be triggered when <code>MyEvent</code> occurs
 
 <li>
 <b>Creating the event emitter instance:</b> We instantiated the <code>AsyncIOEventEmitter</code> class, which acts as 
-the event emitter responsible for dispatching events and invoking the associated event handler callbacks.
+the event emitter responsible for dispatching events and invoking the associated event handler callbacks. It's important 
+to note that the event emitter used can be changed by any of the built-in or custom event emitter implementations.
 </li>
 
 <li>
@@ -190,8 +187,8 @@ is the <code>event_callback()</code>.
 !!! example "Next steps"
 
 	<p style='text-align: justify;' markdown>
-	    Feel free to experiment and build upon this example to explore the full potential of Pyventus in your own 
-		projects. You can register **additional event handlers**, handle **events with different event types**
+	    &emsp;&emsp;Feel free to experiment and build upon this example to explore the full potential of Pyventus in
+		your own projects. You can register **additional event handlers**, handle **events with different event types**
 		or **metadata**, implement **custom event emitters** and **event linkers** based on your application's 
 		requirements. 
 	</p>

docs/release-notes.md

@@ -3,55 +3,81 @@ hide:
   - navigation
 ---
 
+<style>
+	.divider {
+		margin-top: -0.5em !important;
+		margin-bottom: -0.2em !important;
+	}
+</style>
+
 [//]: # (--------------------------------------------------------------------------------------------------------------)
 
-## v0.4.0
+## [v0.4.1](https://github.com/mdapena/pyventus/releases/tag/0.4.1) <small>January 30, 2024</small> { id="0.4.1" }
+
+<hr class="divider">
+
+##### Changed
+
+- Optimized the size of the `sdist` build by including only essential files and directories, such as `/src`, `/tests`,
+  `.gitignore`, `pyproject.toml`, `CITATION.cff`, `README.md` and `LICENSE`.
+- Refactored the dependencies of the docs environment by separating them into an optional dependency called `docs`.
+- Updated the `deploy-docs.yml` GitHub workflow to utilize the new `docs` optional dependency.
+- Updated the `EventEmission` class with the `@final` decorator from the typing module, indicating that it is meant for
+  internal use only and should not be subclassed.
 
-### What's Changed
+##### Fixed
+
+- Addressed minor errors and fixed broken links in the documentation.
+
+[//]: # (--------------------------------------------------------------------------------------------------------------)
 
-##### New Features
+## [v0.4.0](https://github.com/mdapena/pyventus/releases/tag/0.4.0) <small>January 6, 2024</small> { id="0.4.0" }
+
+<hr class="divider">
+
+##### Added
 
 - The `FastAPIEventEmitter` has been added to facilitate seamless integration with `FastAPI` framework and leverage its
   `BackgroundTasks` for event handling.
 - Added comprehensive documentation for `FastAPIEventEmitter`, including tutorials and API references.
 - A `Coveralls.io` workflow has been added to generate a coverage badge and reports.
 - Included permalinks for easy navigation within the documentation.
 
-##### Fixes
+##### Fixed
 
 - Addressed minor errors in the Pyventus documentation.
 
 [//]: # (--------------------------------------------------------------------------------------------------------------)
 
-## v0.3.0
-
-### What's Changed
+## [v0.3.0](https://github.com/mdapena/pyventus/releases/tag/0.3.0) <small>December 29, 2023</small> { id="0.3.0" }
 
-##### Breaking Changes
-
-- Introduced `EventEmission` object to encapsulate the processing of event emissions. This changes the `_execute()`
-  method of EventEmitter but provides a cleaner, more scalable, and efficient approach.
-- Renamed EventEmitter's `_execute()` method to `_process()` to better reflect its purpose of processing event
-  emissions.
-- Renamed all debug flags from `debug_mode` to `debug` for enhanced clarity and consistency.
+<hr class="divider">
 
-##### New Features
+##### Added
 
 - Added `CeleryEventEmitter` implementation to leverage the Celery distributed task queue for event handling.
 - Included documentation for `CeleryEventEmitter` including tutorials and API references.
 
-##### Refactors
+##### Changed
 
 - Restructured documentation for event emitters tutorials and API references.
 - Restructured tests for event emitters tutorials and API references.
 
+##### Breaking Changes
+
+- Introduced `EventEmission` object to encapsulate the processing of event emissions. This changes the `_execute()`
+  method of EventEmitter but provides a cleaner, more scalable, and efficient approach.
+- Renamed EventEmitter's `_execute()` method to `_process()` to better reflect its purpose of processing event
+  emissions.
+- Renamed all debug flags from `debug_mode` to `debug` for enhanced clarity and consistency.
+
 [//]: # (--------------------------------------------------------------------------------------------------------------)
 
-## v0.2.1
+## [v0.2.1](https://github.com/mdapena/pyventus/releases/tag/0.2.1) <small>December 17, 2023</small> { id="0.2.1" }
 
-### What's Changed
+<hr class="divider">
 
-##### Fixes
+##### Fixed
 
 - Fixed issues with invalid links in the documentation.
 - Updated docstring links to the official Pyventus documentation.
@@ -60,16 +86,16 @@ hide:
 
 [//]: # (--------------------------------------------------------------------------------------------------------------)
 
-## v0.2.0
+## [v0.2.0](https://github.com/mdapena/pyventus/releases/tag/0.2.0) <small>December 16, 2023</small> { id="0.2.0" }
 
-### What's Changed
+<hr class="divider">
 
-##### New Features
+##### Added
 
 - This release introduces the `publish to PyPI` workflow, automating the uploading of package builds
   when new releases are created.
 
-##### Changes
+##### Changed
 
 - Badges have been added to the main page of the documentation as well as the readme file.
 - To facilitate academic citations, a `CITATION.cff` file has been added in this release.
@@ -78,16 +104,18 @@ hide:
 - The `mkdocs.yml` file has been updated to include the `git-authors` plugin, which lists the names of documentation
   contributors on their respective pages.
 
-##### Fixes
+##### Fixed
 
 - Minor bug fixes and refactoring have been made in the `deploy-docs` and `run-tests` workflows.
 - Fixed issues with relative links in the documentation.
 
 [//]: # (--------------------------------------------------------------------------------------------------------------)
 
-## v0.1.0
+## [v0.1.0](https://github.com/mdapena/pyventus/releases/tag/0.1.0) <small>December 15, 2023</small> { id="0.1.0" }
+
+<hr class="divider">
 
-### Initial Implementation
+##### Initial Implementation
 
 &emsp;&emsp;This release introduces Pyventus 0.1.0, a modern and robust Python package for event-driven programming.
 Pyventus provides developers with a comprehensive suite of tools and utilities to define, emit, and orchestrate events.

docs/tutorials/emitters/celery/index.md

@@ -94,7 +94,7 @@ custom serializer can be implemented if the default does not meet the specific n
 </p>
 </details>
 
-```Python title="worker.py" linenums="1" hl_lines="8-12 18 21"
+```Python title="worker.py" linenums="1" hl_lines="7-8 13-14 17"
 from celery import Celery
 from pyventus.emitters.celery import CeleryEventEmitter
 

pyproject.toml

@@ -41,6 +41,7 @@ classifiers = [
 Homepage = "https://github.com/mdapena/pyventus"
 Documentation = "https://mdapena.github.io/pyventus"
 Repository = "https://github.com/mdapena/pyventus"
+Changelog = "https://mdapena.github.io/pyventus/release-notes"
 
 # ------------------------------------------------------------------
 # | Project Optional dependencies                                  |
@@ -58,7 +59,18 @@ all = [
 ]
 
 # --------------------
-# | Test dependencies
+# | Docs dependencies
+# ----------
+
+docs = [
+    "mkdocs-material>=9.4.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mkdocs-git-revision-date-localized-plugin>=1.2.1",
+    "mkdocs-git-authors-plugin>=0.7.2",
+]
+
+# --------------------
+# | Tests dependencies
 # ----------
 
 tests = [
@@ -77,6 +89,7 @@ tests = [
 # ----------
 
 dev = [
+    "pyventus[docs]",
     "pyventus[tests]",
     "hatch>=1.8.1",
 ]
@@ -92,6 +105,17 @@ path = "src/pyventus/__init__.py"
 # | Building Target                                                |
 # ------------------------------------------------------------------
 
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/.gitignore",
+    "/pyproject.toml",
+    "/CITATION.cff",
+    "/README.md",
+    "/LICENSE",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/pyventus"]
 
@@ -141,12 +165,8 @@ python = ["3.10", "3.11", "3.12"]
 # ------------------------------------------------------------------
 
 [tool.hatch.envs.docs]
-dependencies = [
-    "mkdocs-material>=9.4.0",
-    "mkdocstrings[python]>=0.24.0",
-    "mkdocs-git-revision-date-localized-plugin>=1.2.1",
-    "mkdocs-git-authors-plugin>=0.7.2",
-]
+dependencies = ["pyventus[docs]"]
+
 [tool.hatch.envs.docs.scripts]
 build = "mkdocs build --clean --strict"
 serve = "mkdocs serve --dev-addr localhost:8000"

src/pyventus/__init__.py

@@ -3,7 +3,7 @@
 customizable event emitters and flexible responses.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 from .core.exceptions import PyventusException
 from .emitters import EventEmitter, EmittableEventType

src/pyventus/emitters/event_emitter.py

@@ -2,7 +2,7 @@
 from asyncio import gather
 from datetime import datetime
 from sys import gettrace
-from typing import List, Type, TypeAlias, Any, Tuple, Dict
+from typing import List, Type, TypeAlias, Any, Tuple, Dict, final
 from uuid import uuid4
 
 from ..core.constants import StdOutColors
@@ -34,14 +34,15 @@ class EventEmitter(ABC):
     at: [https://mdapena.github.io/pyventus/tutorials/emitters/](https://mdapena.github.io/pyventus/tutorials/emitters/).
     """
 
+    @final
     class EventEmission:
         """
         Represents an event emission that has been triggered but whose propagation is not
         yet complete. It provides a self-contained context for executing the event emission,
         encapsulating both the event data and the associated event handlers.
 
-        This class acts as an immutable and isolated unit of work to asynchronously propagate
-        the emission of an event.
+        This class acts as an isolated unit of work to asynchronously propagate the emission
+        of an event.
 
         This class is managed by the `EventEmitter` class, which creates an instance when an
         event is emitted. This instance is then processed by the EventEmitter's `_process()`