python-whistle.github.io/index.html at master · python-whistle/python-whistle.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
---
layout: default
---

<style>
    .btn-outline-inverse {
        color: #fff;
        background-color: transparent;
        border-color: #E95420;
    }
</style>

<div class="header-container jumbotron">
    <div class="container">
        <h1>Whistle</h1>
        <h2>Event Dispatcher for Python</h2>

        <p>Whistle is a simple tool that allow your application components to communicate with each other by dispatching
            events and listening to them.</p>

        <p class="text-center">
            <a class="btn btn-primary btn-lg" href="https://pypi.org/project/whistle/" target="_blank"
               role="button">Install</a>
            <a class="btn btn-primary btn-outline-inverse btn-lg" href="https://python-whistle.readthedocs.io/" target="_blank"
               role="button">Documentation</a>
        </p>
    </div>
</div>


<div class="container">

    <div class="row">
        <div class="col-md-10">
            <h2 class="header-light regular-pad">What is Whistle?</h2>
            <blockquote>
                <p>
                    Whistle is a lightweight Event Dispatcher library for Python 3.10+ that enables decoupled application communication through event dispatching and listening.
                </p>
                <p>
                    It's largely inspired from Symfony's EventDispatcher component.
                </p>
                <p>
                    Using an event dispatcher is a great way to write loosely coupled extensible code, having each part
                    only communicate using light events, making your code more modular, testable, and maintainable.
                </p>
            </blockquote>
        </div>
        <div class="col-md-2 text-center">
            <br>
            <div class="clearfix">
                <div class="pull-left" style="margin-right:0.5em">
                    <a class="github-button" href="https://github.com/python-whistle/whistle/fork"
                       data-icon="octicon-repo-forked" data-size="large" aria-label="Fork Whistle on GitHub"></a>
                </div>
                <div class="pull-left">
                    <a class="github-button" href="https://github.com/python-whistle/whistle" data-icon="octicon-star"
                       data-size="large" data-show-count="true" aria-label="Star Whistle on GitHub">Star</a>
                </div>
            </div>
            <img src="img/whistle-logo.png" alt="Whistle, python's event dispatcher."
                 class="img-responsive">
            <a name="documentation"></a>
        </div>
    </div>

    <hr>

    <div class="row">
        <h2>Key Features</h2>
        <div class="col-md-6">
            <ul>
                <li><strong>Synchronous and asynchronous dispatching</strong> - Choose the right dispatcher for your use case</li>
                <li><strong>Priority-based listener execution</strong> - Control the order listeners run</li>
                <li><strong>Event propagation control</strong> - Stop event flow when needed</li>
            </ul>
        </div>
        <div class="col-md-6">
            <ul>
                <li><strong>Type safety</strong> - Prevent mixing sync and async listeners</li>
                <li><strong>Custom events</strong> - Attach domain-specific data to events</li>
                <li><strong>Zero dependencies</strong> - Lightweight and easy to integrate</li>
            </ul>
        </div>
    </div>

    <hr>

    <div class="row">
        <h2>Quick start</h2>

        <p>Install the <code>whistle</code> package:</p>

        <pre><code> $ pip install whistle</code></pre>

        <h3>Create an event dispatcher</h3>

        <pre><code class="python">from whistle import EventDispatcher

dispatcher = EventDispatcher()</code></pre>

        <h3>Add a listener to react to events</h3>

        <pre><code class="python">def on_spectacle_starts(event):
    print('Please turn down your phones!')

dispatcher.add_listener('spectacle.starts', on_spectacle_starts)</code></pre>

        <p>Or use the decorator syntax for convenience:</p>

        <pre><code class="python">@dispatcher.listen('spectacle.starts')
def on_spectacle_starts(event):
    print('Please turn down your phones!')
</code></pre>

        <h3>Dispatch it!</h3>

        <pre><code class="python">dispatcher.dispatch('spectacle.starts')
# Output: Please turn down your phones!</code></pre>


    </div>

    <hr>

    <div class="row">
        <h2>License</h2>
        <p>
            Whistle and the surrounding material (like this website) is licensed under the Apache License, version 2.0.
        </p>
    </div>

</div>