Skip to content

amitassaraf/python-hooks

Repository files navigation

Python Hooks

Build status Python Version Dependencies Status Code style: black Security: bandit Pre-commit Semantic Versions License Coverage Report GitHub Contributors Issues GitHub pull requests Dev status


A React inspired way to code in Python.

drawing

Made with love by Amit Assaraf
If you like this project, consider starring it on Github ⭐⭐⭐⭐

  • ⚡️ Written with performance in mind (Not using inspect module)
  • 🐍 Support for familiar React like hooks such as use_state, use_effect, use_reducer, use_context and more.
  • 🛠️ Built with plugins support and easy to extend.
  • 🤝 Python 3.9+ compatibility
  • 🪶 Lightweight to remove the need for a lot of boilerplate code.
  • 📦 Support for different backend state-stores.
  • 🔧 Support for hooks-state scoping.
  • 🌎 Redis, Redux, and Zustand plugins out of the box.
  • 🔌 Tested mainly on CPython.

Inspiration

I'll begin be prefacing that this project will not fit everyone's needs. It's a very opinionated project and it's not meant to be a replacement for any of the existing state management libraries. Additionally, if you are trying to squeeze the most performance out of Python this is probably not the right tool for you (Though you might also be using the wrong programming language).

The goal of the project is to provide a simple and familiar way to manage state in Python. It's inspired by the React hooks API and it's meant to be used in a similar way. It can be used to manage state in a single function or in a large project. The state can be stored in memory, in a database or in a file. It's up to you to decide and the library is easily extendable to support any backend.

One of the inspirations for this project was seeing the way junior developers struggle with state management and program structure in Python. This library is intended to provide a sense of familiarity to developers coming from the JavaScript world and to provide a simple way to manage state in Python which will not require a lot of boilerplate code or hurt performance.

It is meant to help write better data-driven code and to help developers focus on the business logic of their code rather than on the plumbing.

Discord | Docs

Note: This project is still in beta and is not recommended for production use just yet. We are working on adding more tests and improving the documentation. If you are interested in contributing, please reach out to me on Discord. The biggest challenge right now is to find a way to handle code versioning, as the state is identified by the frame in which it was created. This means that if you change the code, the state will be lost.


Let's see one API example

As Python is commonly used to create APIs, I wanted to provide one real-world example of using hooks for state management in Flask. Note, that this is just one example and the library can be used in many other ways. See examples for more examples.

drawing

Pretty neat, right?

🚀 Installation

pip install python-hooks

🎯 What's next

Well, that's up to you 💪🏻. We are looking for contributors to help us build this project and make it better. If you are interested in contributing, please reach out to me on Discord or open an issue. In addition we are looking for plugin developers to help us build more plugins for different state stores.

📈 Releases

You can see the list of available releases on the GitHub Releases page.

We follow Semantic Versions specification.

We use Release Drafter. As pull requests are merged, a draft release is kept up-to-date listing the changes, ready to publish when you’re ready. With the categories option, you can categorize pull requests in release notes using labels.

List of labels and corresponding titles

Label Title in Releases
enhancement, feature 🚀 Features
bug, refactoring, bugfix, fix 🔧 Fixes & Refactoring
build, ci, testing 📦 Build System & CI/CD
breaking 💥 Breaking Changes
documentation 📝 Documentation
dependencies ⬆️ Dependencies updates

GitHub creates the bug, enhancement, and documentation labels for you. Dependabot creates the dependencies label. Create the remaining labels on the Issues tab of your GitHub repository, when you need them.

📋 Roadmap

  • Finish documentation
  • Improve frame identifier without hurting performance
  • Add redux plugin
  • Async support ⚡
  • Handle code versioning (Moving state around the code) [!]
  • Develop state-debugger plugin
  • Test and adapt to PyPy, Jython, IronPython
  • Support for more hook backends
    • MongoDB
    • Postgres
    • MySQL
    • SQLite

See the open issues for a full list of proposed features (and known issues).

🛡 License

License

This project is licensed under the terms of the MIT license. See LICENSE for more details.

📃 Citation

@misc{python-hooks,
  author = {Amit Assaraf},
  title = {A React inspired way to code in Python},
  year = {2023},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/amitassaraf/python-hooks}}
}