Merge pull request #1 from pomponchik/develop

0.0.1

Author: pomponchik

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: pomponchik
+
+---
+
+## Short description
+
+Replace this text with a short description of the error and the behavior that you expected to see instead.
+
+
+## Describe the bug in detail
+
+Please add this test in such a way that it reproduces the bug you found and does not pass:
+
+```python
+def test_your_bug():
+    ...
+```
+
+Writing the test, please keep compatibility with the [`pytest`](https://docs.pytest.org/) framework.
+
+If for some reason you cannot describe the error in the test format, describe here the steps to reproduce it.
+
+
+## Environment
+ - OS: ...
+ - Python version (the output of the `python --version` command): ...
+ - Version of this package: ...

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,26 @@
+---
+name: Documentation fix
+about: Add something to the documentation, delete it, or change it
+title: ''
+labels: documentation
+assignees: pomponchik
+---
+
+## It's cool that you're here!
+
+Documentation is an important part of the project, we strive to make it high-quality and keep it up to date. Please adjust this template by outlining your proposal.
+
+
+## Type of action
+
+What do you want to do: remove something, add it, or change it?
+
+
+## Where?
+
+Specify which part of the documentation you want to make a change to? For example, the name of an existing documentation section or the line number in a file `README.md`.
+
+
+## The essence
+
+Please describe the essence of the proposed change

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: pomponchik
+
+---
+
+## Short description
+
+What do you propose and why do you consider it important?
+
+
+## Some details
+
+If you can, provide code examples that will show how your proposal will work. Also, if you can, indicate which alternatives to this behavior you have considered. And finally, how do you propose to test the correctness of the implementation of your idea, if at all possible?

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,12 @@
+---
+name: Question or consultation
+about: Ask anything about this project
+title: ''
+labels: guestion
+assignees: pomponchik
+
+---
+
+## Your question
+
+Here you can freely describe your question about the project. Please, before doing this, read the documentation provided, and ask the question only if the necessary answer is not there. In addition, please keep in mind that this is a free non-commercial project and user support is optional for its author. The response time is not guaranteed in any way.

.github/workflows/lint.yml

@@ -0,0 +1,36 @@
+name: Lint
+
+on:
+  push
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+          python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      shell: bash
+      run: pip install -r requirements_dev.txt
+
+    - name: Install the library
+      shell: bash
+      run: pip install .
+
+    - name: Run ruff
+      shell: bash
+      run: ruff check transfunctions
+
+    - name: Run ruff for tests
+      shell: bash
+      run: ruff check tests

.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  pypi-publish:
+    name: upload release to PyPI
+    runs-on: ubuntu-latest
+    # Specifying a GitHub environment is optional, but strongly encouraged
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+            python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        shell: bash
+        run: pip install -r requirements_dev.txt
+
+      - name: Build the project
+        shell: bash
+        run: python -m build .
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests_and_coverage.yml

@@ -0,0 +1,49 @@
+name: Tests
+
+on:
+  push
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [macos-latest, ubuntu-latest, windows-latest]
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+          python-version: ${{ matrix.python-version }}
+
+    - name: Install the library
+      shell: bash
+      run: pip install .
+
+    - name: Install dependencies
+      shell: bash
+      run: pip install -r requirements_dev.txt
+
+    - name: Print all libs
+      shell: bash
+      run: pip list
+
+    - name: Run tests and show coverage on the command line
+      run: |
+        coverage run --source=transfunctions --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m --fail-under=90
+        coverage xml
+
+    - name: Upload coverage to Coveralls
+      if: runner.os == 'Linux'
+      env:
+        COVERALLS_REPO_TOKEN: ${{secrets.COVERALLS_REPO_TOKEN}}
+      uses: coverallsapp/github-action@v2
+      with:
+        format: cobertura
+        file: coverage.xml
+
+    - name: Run tests and show the branch coverage on the command line
+      run: coverage run --branch --source=transfunctions --omit="*tests*" -m pytest --cache-clear --assert=plain && coverage report -m --fail-under=90

.gitignore

@@ -0,0 +1,11 @@
+__pycache__
+.pytest_cache
+.DS_Store
+test.py
+*.egg-info
+dist
+venv
+build
+.ruff_cache
+.mypy_cache
+.coverage

.ruff.toml

@@ -0,0 +1 @@
+lint.ignore = ['E501', 'E712']

README.md

@@ -1 +1,76 @@
-# transfunctions
+# transfunctions
+
+[![Downloads](https://static.pepy.tech/badge/transfunctions/month)](https://pepy.tech/project/transfunctions)
+[![Downloads](https://static.pepy.tech/badge/transfunctions)](https://pepy.tech/project/transfunctions)
+[![Coverage Status](https://coveralls.io/repos/github/pomponchik/transfunctions/badge.svg?branch=main)](https://coveralls.io/github/pomponchik/transfunctions?branch=develop)
+[![Lines of code](https://sloc.xyz/github/pomponchik/transfunctions/?category=code)](https://github.com/boyter/scc/)
+[![Hits-of-Code](https://hitsofcode.com/github/pomponchik/transfunctions?branch=main)](https://hitsofcode.com/github/pomponchik/transfunctions/view?branch=main)
+[![Test-Package](https://github.com/pomponchik/transfunctions/actions/workflows/tests_and_coverage.yml/badge.svg)](https://github.com/pomponchik/transfunctions/actions/workflows/tests_and_coverage.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/transfunctions.svg)](https://pypi.python.org/pypi/transfunctions)
+[![PyPI version](https://badge.fury.io/py/transfunctions.svg)](https://badge.fury.io/py/transfunctions)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+This library is designed to solve one of the most important problems in python programming - dividing all written code into 2 camps: sync and async. We get rid of code duplication by using templates.
+
+
+## Table of contents
+
+- [**Quick start**](#quick-start)
+- [**The problem**](#the-problem)
+
+
+## Quick start
+
+Install it:
+
+```bash
+pip install transfunctions
+```
+
+And use:
+
+```python
+from asyncio import run
+from transfunctions import (
+    transfunction,
+    sync_context,
+    async_context,
+    generator_context,
+)
+
+@transfunction
+def template():
+    print('so, ', end='')
+    with sync_context:
+        print("it's just usual function!")
+    with async_context:
+        print("it's an async function!")
+    with generator_context:
+        print("it's a generator function!")
+        yield
+
+function = template.get_usual_function()
+function()
+#> so, it's just usual function!
+
+async_function = template.get_async_function()
+run(async_function())
+#> so, it's an async function!
+
+generator_function = template.get_generator_function()
+list(generator_function())
+#> so, it's a generator function!
+```
+
+As you can see, in this case, 3 different functions were created based on the template, including both common parts and unique ones for a specific type of function.
+
+You can also quickly try out this and other packages without having to install using [instld](https://github.com/pomponchik/instld).
+
+
+## The problem
+
+Since the `asyncio` module appeared in Python more than 10 years ago, many well-known libraries have received their asynchronous alternates. A lot of the code in the Python ecosystem has been [duplicated](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and you probably know many such examples.
+
+The reason for this problem is that the Python community has chosen a way to implement asynchrony expressed through syntax. There are new keywords in the language, such as `async` and `await`. Their use makes the code so-called "[multicolored](https://journal.stuffwithstuff.com/2015/02/01/what-color-is-your-function/)": all the functions in it can be red or blue, and depending on the color, the rules for calling them are different. You can only call blue functions from red ones, but not vice versa.
+
+I must say that implementing asynchronous calls using a special syntax is not the only solution. There are languages like Go where runtime can independently determine "under the hood" where a function should be asynchronous and where not, and choose the correct way to call it. A programmer does not need to manually "colorize" their functions there. Personally, I think that choosing a different path is the mistake of the Python community, but that's not what we're discussing here.