Some readers found my articles boring, while others thought they were too technical and hard to understand. Some people even had trouble reading articles in English.

So I thought, why not use LLMs for some post-production work and publish different versions of an article I write on Hashnode?

Theory

Hashnode uses a GitHub repository to create backups for the articles you publish on Hashnode. If you enable this feature in your Hashnode dashboard, a username/hashnode repository will be created on your GitHub profile.

From then on, whenever you publish or edit an article, it will automatically be pushed to that GitHub repository, and here is when magic happens! 🪄

Based on the configuration given to Notio, it carries out different tasks on the article. In the end, the result is a markdown file with the new version of the article inside the backup repository.

How Notio Works

Notio functions as a GitHub CI pipeline (GitHub Action). It connects to a Hypermode GraphQL instance and processes the article by making API calls to the instance.

Once the transformed article is received, it is saved as a Markdown file in the backup directory. Since both Hashnode and GitHub use similar Markdown syntax, the output articles stay readable on GitHub.

LLM Features

Notio provides several LLM features. Let's begin with the most important one.

Article translation

You can receive a translated version of your article in any language on your GitHub just minutes after publishing it on Hashnode. (both RTL and LTR languages are supported)

Generating questions

This feature allows you to generate any number of questions, with or without answers, about the published article and save them as a markdown document.

Generate abstraction

If you need to create a brief summary of your article, this feature is perfect for you. Just a minute after you publish your article on Hashnode, you'll have its summary in the repository.

Simplify article

You can use this feature to create a simpler version of your article for readers who need a basic understanding of the topic. This version might include fewer code blocks and lighter discussion topics, but it still covers all sections of the article.

Setup & Usage

If you want to set up Notio for your Hashnode blog, follow these steps.

1. Enable blog backup from Hashnode

Navigate to your blog settings. From the sidebar, select "GitHub” and follow the instructions.

2. Create a Hypermode instance

Clone this Hypermode sample instance repository. Follow this document to deploy your own GraphQL instance on Hypermode.

3. Grab the endpoint URL and API key

Once your instance is deployed to Hypermode, retrieve the endpoint URL from the Hypermode dashboard and the API key from the instance settings.

4. Store the secrets

Navigate to the backup repository that Hashnode has just created for you on your GitHub profile. Go to "Settings" > "Secrets and variables" > "Actions" and create the following secrets.

• HYPERMODE_ENDPOINT_URL: The endpoint URL–taken from the Hypermode dashboard.

• HYPERMODE_API_TOKEN: The API token–taken from the Hypermode instance settings.

5. Use Notio

Now that everything is set up and the model is ready to respond, create a workflow file in the backup repository at .github/workflows/notio-ci.yml. For now, paste the following YAML configuration into it.

name: Notio LLM CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    name: Running the action
    steps:
      - name: checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

Two more steps need to be added to this YAML file. The next step involves using Notio. The steps below show how to use each LLM feature. Choose one and configure it according to your needs.

• translate-article: To translate the article.

    - name: Running Notio
      uses: lnxpy/notio@main
      with:
        method: translate-article
        path: dutch/  # default: transformed_articles/
        translate_to: Dutch # default: English
        hypermode_endpoint: ${{ secrets.HYPERMODE_ENDPOINT }}
        hypermode_api_token: ${{ secrets.HYPERMODE_API_TOKEN }}
  

• question-generation: To generate questions about the article.

    - name: Running Notio
      uses: lnxpy/notio@main
      with:
        method: generate-questions
        path: questions/
        question_limit: 10 # default: 20
        include_answers: false # default: true
        hypermode_endpoint: ${{ secrets.HYPERMODE_ENDPOINT }}
        hypermode_api_token: ${{ secrets.HYPERMODE_API_TOKEN }}
  

• abtract-article: To summarize and generate an abstraction from the article.

    - name: Running Notio
      uses: lnxpy/notio@main
      with:
        method: abstract-article
        path: abstractions/
        hypermode_endpoint: ${{ secrets.HYPERMODE_ENDPOINT }}
        hypermode_api_token: ${{ secrets.HYPERMODE_API_TOKEN }}
  

• simplify-article: To simplify the article.

    - name: Running Notio
      uses: lnxpy/notio@main
      with:
        method: simplify-article
        path: simplified_articles/
        hypermode_endpoint: ${{ secrets.HYPERMODE_ENDPOINT }}
        hypermode_api_token: ${{ secrets.HYPERMODE_API_TOKEN }}
  

And finally, add the commit step to ensure the Notio articles are submitted to the repository and visible to your audiences.

- name: Commiting
  uses: EndBug/add-and-commit@v9
  with:
    default_author: github_actions
    message: 'article updated'

Here is a sample notio-ci.yml file showing how to use the question-generation method.

name: Notio LLM CI

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    name: Running the action
    steps:
      - name: checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Running Notio
        uses: lnxpy/notio@main
        with:
          method: generate-questions
          path: questions/
          question_limit: 20
          include_answers: true
          hypermode_endpoint: ${{ secrets.HYPERMODE_ENDPOINT }}
          hypermode_api_token: ${{ secrets.HYPERMODE_API_TOKEN }}

      - name: Commiting
        uses: EndBug/add-and-commit@v9
        with:
          default_author: github_actions
          message: 'article updated'

Now, whenever you publish or edit an article on Hashnode, Notio will begin processing it and perform the LLM operation you have specified.

Example

I'm using Notio for my Hashnode blog. When I published this article, Notio generated 10 questions about the article and stored them in my Hashnode backup repository. You can visit it here.

Tech Stacks

• PyAction: https://pyaction.imsadra.me/

• Hypermode: https://hypermode.com/

Useful Links

• Notio repository: https://github.com/lnxpy/notio

• Hypermode model instance: https://github.com/lnxpy/notio-model

Conclusion

With the rapid growth of AI and LLMs, we'll see significant improvements in our CI cycles. We won't need to review and rewrite articles ourselves because we have AI!

Special thanks to Hypermode and Hashnode for setting up this awesome hackathon. 🍻

Working with it is as simple as writing blogs on Hashnode but in an organized way. I decided to write my fresh experience of using Docs for a public open-source tool.

I Should’ve Reconsidered My Decision

As an open-source developer, I think I should’ve reconsidered my decision when I first decided to deploy on Hashnode Docs.

The separation of docs and project

I’m feeling a few concerns about Hashnode Docs. The main reason is that I’m separating the documentation from my codebase and hosting it elsewhere.

It's like a double-edged sword. You can modify and deploy it very quickly, but only your team has access to the docs, and not everyone can contribute to it.

There is a "GitHub" feature that will be available soon, but I don't think it will be the same as keeping the documentation within the scope of the project itself. It seems more like a backup system for the documentation in my opinion.

Lack of customizability

I moved my documentation from MkDocs Material, which was highly customizable. It offered many plugins and extensions, and you could modify existing features, which was really nice.

I haven't seen these options on Hashnode. Remember, Hashnode Docs isn't just for developers. In my view, it's designed to let you document anything, regardless of the level of programming knowledge. On the other hand, tools like MkDocs and Sphinx are meant for developers who prefer to work directly in a text editor.

Code highlighting feature

You include many code snippets in your docs, and this is another area where Hashnode could improve. The syntax highlighting feature is somewhat lacking, as it doesn't recognize all the keywords in some languages, which can be frustrating at first. Considering the fresh modern look of (/callout), the code snippets could be more visually appealing. I strongly feel that code snippets haven't changed much since the first release of Hashnode, and Hashnode Docs is still using the same setup.

Including badges, icons, and in-line images

Including badges is another issue with Docs. I wish I could add some Shields.io badges to my docs to show the current status of my project.

I tried to use tables to put badges in them but you can’t put images inside the table cells. I tried buttons, although I managed to put the badges in them but the looking wasn’t too good.

No versioning or tagging feature

There is no recovery feature yet. If you delete any part of your document, you can't retrieve it back. Tagging and versioning in documents are very important features. Fortunately, Hashnode offers "Revision History" for blogs. I hope they add the same functionality for documents soon, perhaps with the ability to tag specific states of the docs.

No translation feature

If you want to translate your docs into another language, there is currently no feature available for that.

Things I Love About Hashnode Docs

I switched to Hashnode Docs for a reason. Let's look at what really caught my attention and convinced me to move to Hashnode Docs.

New commands and markdown items

There are many features that help you present your docs effectively. You can use /steps, /card, /accordion, /tabs, and even /button to customize your docs and make the reading experience more engaging. None of these markdown items are available on blogs which makes docs more unique.

No more CI pipeline or deployment

You don't need a CI pipeline to deploy your documentation after each change, which allows for continuous publication—this is fantastic. Additionally, making changes to your documents is easy and straightforward.

SEO is the next level

In a word, Hashnode’s SEO team is outstanding. Even if you try to harm your docs' SEO, Hashnode still manages to share your docs with the world. It's amazing how powerful this is.

Perfect choice for open-source projects

If you're looking for a platform to publish the documentation for your open-source project, Hashnode Docs is a great choice. It includes features that read various parameters from the GitHub repository you specify, such as the number of stars your repository has.

Fast to navigate and engage

Its routing system is quick, letting you move instantly between pages and documents without waiting for the full page to load. Only the content section reloads.

Final Word

Keep in mind, it's only been a few months since Hashnode Docs was released. So, many of my complaints and concerns might disappear in a few months.

Stay with me as we discuss the basics of Generic Typing in Python and some best practices at the end.

What Does Generic Typing Help With?

This fascinating feature allows you to make type-checking more dynamic. Sometimes, we don't know the types of input parameters.

Before we continue, I encourage you to take a moment to try solving this problem.

How would you type-hint a function that takes one parameter and that’s a list of objects of any type (int, str, User, Book, etc) and returns just one random object of that type?

Any Turns off the Type-Checking!

During that challenge, you might have considered the following thought processes. Let's take a look.

Thought Process 1:

My function should take one parameter, which is a list of any type (List[Any]), and return a random single item from that list (Any).

def select(items: List[Any]) -> Any:
    return random.choice(items)

Answer:

This is incorrect. Although your type-checker might still pass the type-checking, there is a significant mistake in this typing. List[Any] means a list that can be empty or filled with items of any type. This allows the function to be called in a way that violates the requirement that the parameter should be a list of items of the same type.

select([1, "b", "c", "d", False, 3.14])

The type Any somehow neutralizes the type-checker and hides its pointer from being type-checked.

item: Any = ...  # just like we've put `type: ignore` here

Be very careful with Any and make sure you really need its effect.

Thought Process 2:

I can explicitly define what type my parameter can take. That way, not only I haven’t used the type Any, I have explicitly defined the input and output type.

def select(items: List[int | str | bool | float]) -> int | str | bool | float:
    return random.choice(items)

Answer:

This is a better solution, but it still doesn't fully meet the challenge where we said the function parameter could be anything. It might not be a string or an integer, for example. This function only works for the built-in types. What if I wanted to call it like this?

from typing import NewType

def select(...):
    .

User = NewType("User", str)
users = [User("Abby"), User("Chris"), User("Nick")]

user = select(users)

file.py:12: error: Argument 1 to "select" has incompatible type "list[User]"; expected "list[int | str | bool | float]"  [arg-type]

Not only did our type-checker (mypy) fail to check it, but it also doesn't meet the challenge.

Using Generic Typing

It’s a newly added syntax to Python. Yet I haven’t seen many people using it as they are still releasing for older Python versions like 3.8, 3.9, 3.10, and 3.11. Generic typing was introduced in Python 3.12.

Now, let’s talk about how we can use this feature to solve the challenge we described earlier.

Structure and Syntax

The structure is quite simple. You define new type variables and use them accordingly when defining the function. Just like defining variables that don't have a value at the time of declaration, you define placeholders in brackets right before the parentheses. (Here, I've declared only one variable/placeholder named T)

def FUNCTION_NAME[TYPES](ARGS..) -> TYPE:

def select[T](items...

And you can use it later when specifying the type of parameters and the return value of your function.

def select[T](items: List[T]) -> T:
    ...

Now, let’s define the above function. It has declared one T type variable and says, the items parameter can be a list of anything and I’ll consider that as T for now. That T is the placeholder for any time that items might have.

select(items=[1, 2, 3, 4, 5]) # T=int   &  List[T] = List[int]
select(items=["a", "b", "c"]) # T=str   &  List[T] = List[str]
select(items=[1.2, 1.3, 1.4]) # T=float &  List[T] = List[Float]

# Therefore, we have..
users = [User("Abby"), User("Chris"), User("Nick")]
select(items=users)           # T=User  &  List[T] = List[User]

As you can see, the type represented by T changes dynamically based on the values we put in the items parameter. We can now explain the select() function like this:

• Function definition: def select[T](items: List[T]) -> T:

• Type variable(s)/placeholder(s): T

• Input type: List of any similar type

• Output type: A type similar to one of the list items

Let’s Practice

P1: Now, let's say our function takes only one item and returns a tuple containing three of that item.

Answer:

def convert[B](item: B) -> Tuple[B, B, B]:
    return (item, item, item)

Hint: We use the letter "T" as the default primary type placeholder by convention, but you can choose any name you prefer as in the above example, we used the letter “B”.

P2: Let’s say we need a function that takes two parameters of different types and returns a tuple containing those items.

Answer:

def convert[A, B](first: A, second: B) -> Tuple[A, B]:
    return (first, second)

P3: A function that takes an ID and a list of dictionaries, where each dictionary has exactly three pairs (id, username, and is_verified), and returns the item that matches the given ID.

Hint: Avoid defining the type Users in this example to better understand Generic Typing. Defining it would make Generics seem unnecessary in this case.

Answer: You figure it out! :))

Conclusion

Generic Typing is a pretty new and hot topic in Python. It's helpful when defining functions and classes. In this article, we explored the function side of this powerful syntax. Hopefully, you found it useful.

Here's a quick preview of what we'll have by the end of this tutorial. Take a look at this example below.

In the example above, PyAction is a Python library (which I maintain and used to create this project), and I used the action mentioned earlier to create that green graph badge that displays the PyPI download rate of the package over the past 15 days.

Follow the following steps to create and show this badge on your own repositories.

1. Create a new CI pipeline

To use this action, you need a dedicated CI pipeline. To do this, create a .yml or .yaml file in the .github/workflows/ directory of your repository. (If this directory doesn’t exist, create it)

I’m going to name it pypi_chart.yml so its full path would be .github/workflows/pypi_chart.yml in my repository.

2. Paste this action usage in the yml file

Paste the following pipeline usage in the yml file of yours.

name: Update the PyPI chart badge

on:
  schedule:
    - cron: "0 0 1 * *"  # <= runs every month (cron pattern)
  workflow_dispatch:

jobs:
  update-chart-badge:
    name: Updating the pypi chart badge
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Updating the badge
        uses: lnxpy/pypi-chart-badge@v1
        with:
          package_name: <PACKAGE-NAME> # <= here goes your package name

      - uses: EndBug/add-and-commit@v9
        with:
          default_author: github_actions
          message: 'chart badge updated'

This pipeline will run every month to create or update the badge. You can use any cron pattern and replace it with the one on line 5.

Since this pipeline includes workflow_dispatch:, you can run it manually at any time. We will first run it manually to generate the badge, and then let it run automatically for future executions.

Don't forget to update the package_name parameter on line 20 with the name of your Python package.

On the last line, you can set any commit message you want when the badge is updated in your repository.

3. Giving access to the workflow

Now, you need to grant write access to the workflow so it can push the updated badge to your repository.

Simply on the repository page, navigate to “Settings”. From the side panel, choose “Actions” > “General”.

Scroll all the way down until you find “Workflow permissions”. Select “Read and write permissions" and hit save.

Now, your workflow has writing access to your repository.

4. Testing

Go to the “Actions” panel of your repository. From the side panel, choose the “Update the PyPI chart badge” workflow and run it.

After a few seconds, you’ll see the .pypi_chart/badge.svg is added to your repository. Now if you edit your README.md file and add that SVG file, you’ll see the badge showing up perfectly.

# Package ![badge](.pypi_chart/badge.svg)

Options

There are a bunch of options that you can use to customize the badge. Copy and paste any of the following options into your pipeline.

      - name: Updating the badge
        uses: lnxpy/pypi-chart-badge@v1
        with:
          package_name: <PACKAGE-NAME>

          # badge width size in px (default: 60)
          badge_width: 200

          # badge height size in px (default: 20)
          badge_height: 65

          # plot color (CSS color or HEX)
          badge_color: '#ff05e6'

          # days limit (default: 15)
          days_limit: 25

          # output path (default: .pypi_chart/)
          output_path: media/

          # output file name (default: badge.svg)
          file_name: badge.png

Links

• Action repository: https://github.com/lnxpy/pypi-chart-badge

• Action on GitHub marketplace: https://github.com/marketplace/actions/pypi-chart-badge

• PyAction repository: https://github.com/lnxpy/pyaction

• PyAction docs: https://pyaction.imsadra.me

Here is the article showcasing Hey:

I Was the Only User of My Product 😞

At first, I was the only user. Despite sharing it on every social media platform, I felt disappointed when nobody noticed it. No one seemed to care about what I was doing, and my repo had only 8 stars (mine included).

Fortunately, I had a network of smart, awesome people. Since Hey was a hackathon idea, I felt hesitant about sharing posts about it after the event ended. I made something for the hackathon, and it did its job. Everyone who participated in the hackathon seemed to enjoy it at the time. But do I really want to keep maintaining the project? Is my network going to keep ignoring it? Does anybody else want to hear about Hey?

I Gave It a Shot 🎯

Hey was presented very well. In fact, I believe the intro video about Hey was one of the key reasons for its success during the hackathon. I couldn't let that masterpiece fade away. I had to show it off once again!

Here is the intro:

After the hackathon ended, I was maintaining only a few repositories. So, I decided to work on multiple projects. I planned to add some cool features to Hey and improve it a bit thinking that might attract some attention.

The very first version of Hey was difficult to set up. As a user, I would never install it!

If you wanted to use Hey, you had to go through several steps, like creating an account on MindsDB, copying and pasting some SQL queries, setting up the LLM model, and installing Hey. Developers might be okay with this, but what about anyone else?

The first step was to improve the accessibility. I developed Hey top to bottom in 4 days. I assumed it would be a one-time development process, so I built it just to work.

Fortunately, its codebase wasn't too large to refactor. I managed to redesign it using a completely different approach for connecting to the LLM. The project saw massive performance improvements in different aspects.

• Accessibility: Now, all you need to run it is a token!

• Performance: The new redesign resulted in much faster response time.

• Design: The new codebase design allowed me to focus more on the UI and UX.

What To Do Next 🤔

I had posted about the initial version of Hey with my network before, but it didn't get much attention as I said. Maybe it was because it was an app created for a hackathon, or perhaps they found it a bit hard to use. Either way, it didn't seem promising to me.

I had to try something new, something fair with a decent chance of engagement. I was familiar with Product Hunt. I knew people used it to share their startup ideas or demonstrate an MVP. I didn't realize that open-source projects were also part of that community.

So I went for it!

I Had Almost No Strategy 🤯

At first, I didn't know much about the Product Hunt platform. I assumed it was mainly about the number of followers and the network you had, which would help you get more attention and engagement. As a newcomer, I thought my project wouldn't stand a chance of being noticed by others so I didn't take it seriously and didn’t put %100 of myself into it. Soon I realized that it made my first mistake.

I was still a bit upset about the lack of engagement Hey received on other social platforms before, so I didn't plan any specific strategy for this one and just went through it.

I looked at some of the top-voted products of the day to see how they were designed. Meanwhile, I wondered, what if my project could make it up there?

I also read a few articles about best practices for launching on Product Hunt to at least have an idea of what I was doing. Noticed these key points.

• Choose a simple precise slogan for your product.

• Use a graphic designing tool to create a few templates for its homepage.

• Your product's logo and slogan matter the most.

• Keep your product's description short, simple, and informative.

So I followed almost everything I learned from those resources, but I still had some ignorance!

I launched it, posted about it on LinkedIn and Twitter, and then went to bed.

This is pretty much the strategy that I followed. It took me about three hours to launch. Looking back, I realize I could have done way better with more planning. Some entrepreneurs wait to launch at specific times, even if their product has been ready for months, intentionally missing out on potential income their product could have made.

I'm not an entrepreneur, and this article isn't the best place to learn about entrepreneurship. I'm just sharing my experience with one (seemingly) successful launch on Product Hunt. 😅

Product Hunt Is a Fair Deal 🤌

I woke up the next day and turned off the airplane mode of my phone. Immediately, I was flooded with dozens of notifications on LinkedIn and X. So many email notifications from Product Hunt. I had over 30 new messages in my inbox. At first, I thought these were bots crawling Product Hunt to message creators and advertise their work. This seemed reasonable to me, so I didn't take it seriously.

At first, I didn't expect any difference between launching on Product Hunt and sharing a post about the product on social media. That's why I was surprised when I opened my browser to Google something and suddenly saw my project listed as the 3rd product of the day with 110 upvotes!!

I was really surprised. I had put only three hours for this launch and didn't even put in much effort, but it still did great. I shared this image everywhere and tagged all my friends to support and check it out. I even reshared the intro video to get more engagement. Now, I was seeing it work! 🥳

Luckily, with the help of my network, I even managed to reach 1st place for a couple of hours but eventually secured the 2nd spot, earning the title "The 2nd Product of the Day". This was more than enough for me, especially since I had only one follower when I launched.

I was amazed at how (fairly) competitive Product Hunt is. Everyone has an equal chance to showcase their products. (Let's ignore those who pay for subscriptions)

With a bit of hard work, you can succeed. Just like how I did it with only 1 follower and almost no engagement at the time on the platform. Of course, you’re idea and implementation matter. 🙃

Getting Upvotes and Attentions ⬆️

Your product's logo, name, and slogan are the first things users will notice, so you should put serious effort into them. Use your design skills to convince them to click on it. If you're not skilled enough in those areas, let others do them for you. Ask your friends. Luckily, I had a bit of knowledge.

When a user opens your product page, the first thing that he/she notices is the images and media you've attached. My YouTube video did a good job there. It was less than two minutes long and effectively conveyed the message to the users. So, upload a video if you can. (It doesn't need to be recorded with the best high-tech microphone and laptop)

If you can't upload a video, design eye-catching images to convey your message. Don't overload them with information. They should be bite-sized but informative, using just a bold keyword or two. Use graphical elements to highlight and demonstrate the strengths of your product.

The next thing that catches their attention is the description of your product. This is your most valuable shot right there as users will decide here whether to upvote and comment or close the tab and never return!

Always start strong in the first paragraph. Grab their attention and convince them to keep reading. Most people get bored while reading, so I kept it shot, very simple, and informative. If your product has a longer description, make sure to begin with your best sentences. It's markdown-supported, so remember to use bullet points and emojis.

One thing that I didn’t know about at the time was that whenever someone launches on Product Hunt, he also writes the first comment on the product and talks about the idea and puts more information there. I’d highly recommend that if your product description is too long.

What Then 🔮

Well, I don't know what to do then as for me, it's the first time I'm experiencing "my then". I've got so many comments on my launch. So many feature requests.

The only expectation I have is to see fewer engagements in my future launches. Usually, the first launch makes the biggest impact unless you take a major step forward and offer something truly impressive, like how OpenAI introduced GPT-4o. Therefore, I need to attract more people from other fields while also working on cool features for the next launch.

Here I've listed the steps that I'd take for now.

• Expand the project to cover more areas and engage people from both tech and non-tech fields.

• Work on the new feature requests.

• Demonstrate other aspects of my project by creating more content.

• Ease the accessibility.

These steps seem to be positively effective. They might be the worst decisions to make right now, I don't know. But I'm not experienced and I don't have time to study "Things to do after a successful launch on Product Hunt". Most importantly, I wouldn't blame myself if I fail because it's my first time and I'm seeking experience.

I can learn from failure, not success. Success only makes me temporarily happy, but failure teaches me the path to lasting happiness.

The Last Word ✍️

Always take your shot. If it doesn't work, try again. Fortunately, you have an unlimited supply of arrows. One day, you'll see it hit.

Thank you for reading this article. I've included links to my product here. Please take a look and share your thoughts.

• Hey! on Product Hunt: https://www.producthunt.com/products/hey-30620d3c-3330-4c6a-86cd-8cf9930a2490/launches

• Hey! on GitHub: https://github.com/lnxpy/hey

Before we go ahead, this is the full patch note about this new release.
The biggest change introduced in the early 3.13 patch notes is that the Global Interpreter Lock (GIL) is now droppable, and you can disable it in certain cases!

1. GIL & JIT

CPython will run with the GIL disabled when configured using the --disable-gil option at build time. To check if the current interpreter is configured with --disable-gil, run the following command:

... -c "import sys; sysconfig.get_config_var('Py_GIL_DISABLED')"

What's more, there will be an experimental version of a just-in-time compiler (JIT) that is disabled by default. You can use as easy as passing an option or by creating your own specific build of CPython 3.13.

It's been quite a while since PyPy introduced its high-performance garbage collector along a JIT compiler. These features have shown great promises.

All of this leads us to realize that CPython 3.14 will be a significant performance improvement, not only for users but also for all frameworks built on top of Python.

Now, without further ado, let's talk about some of the changes.

2. A Better Interactive Interpreter

The new interpreter provides more detailed error messages and tracebacks, helping you catch bugs and issues even faster. They are more colorful. You can disable this behavior by setting PYTHON_COLORS and NO_COLOR environment variables.

PYTHON_COLORS=0 python3.13 main.py

If you write a script inside a .py file with a file name similar to one of the standard library names, such as random, you would typically get a circular import error.

$ python3.12 random.py
Traceback (most recent call last):
  File "/home/random.py", line 1, in <module>
    import random; print(random.randint(5))
    ^^^^^^^^^^^^^
  File "/home/random.py", line 1, in <module>
    import random; print(random.randint(5))
                         ^^^^^^^^^^^^^^
AttributeError: partially initialized module 'random' has no attribute 'randint' (most likely due to a circular import)

But now, you get a more precise exception.

$ python3.13 random.py
Traceback (most recent call last):
  File "/home/random.py", line 1, in <module>
    import random; print(random.randint(5))
    ^^^^^^^^^^^^^
  File "/home/random.py", line 1, in <module>
    import random; print(random.randint(5))
                        ^^^^^^^^^^^^^^
AttributeError: module 'random' has no attribute 'randint' (consider renaming '/home/random.py' since it has the same name as the standard library module named 'random' and the import system gives it precedence)

The same rule applies to third-party packages.

If you call a function with an incorrect parameter name, the interpreter will guess what you meant and suggest the correct name.

>>> "better error messages!".split(max_split=1)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    "better error messages!".split(max_split=1)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
TypeError: split() got an unexpected keyword argument 'max_split'. Did you mean 'maxsplit'?

3. No More Functions in REPL

Now, you can call help(), exit(), and quit() commands without the parentheses.

4. Deprecation Warnings

The warning standard library is used to alert developers about deprecations, future removals, and similar issues. In Python 3.13, there is a @deprecation decorator that allows you to add deprecation warning messages to any of your components.

from warnings import deprecated

@deprecated("Use PayPalPaymentProcessor instead")
class PaymentProcessor:
    ...

class PayPalPaymentProcessor:
    ...

Once a user tries to use any of the deprecated components, a warning will appear in the prompt. For functions, that happens on calls; for classes, on instantiation and on creation of subclasses.

5. New Typing Features

We all know that Python itself doesn't enforce types. You can define a function that takes a parameter name: str and still pass an integer to that function. So, working on the typing module means improving static type checkers even more, and you should use them.

ReadOnly type

In Python 3.13, we have typing.ReadOnly, which can be applied to items of a TypedDict to make them read-only. If you try to change the item value, you can, but your type checker should raise an error.

class Student(TypedDict):
   idn: ReadOnly[str]
   gpa: float

def modify_student(s: Student) -> None:
   s["gpa"] = 4.0  # allowed
   s["idn"] = "24315"  # typechecker error

TypeIs type

This type is assigned to the return value of callables (like functions) that return booleans, indicating whether a variable is an object of a specific type or not.

Consider the following simple function.

def is_student(s: Student):
    return isinstance(s, Student)

Similar to typing.List and typing.Union, it accepts any generic or custom types, so you should use it like TypeIs[SomeType]. Now, let's add a type hint to the return value of that function using TypeIs.

from typing import TypeIs

def is_student(s: Student) -> TypeIs[Student]:
    return isinstance(s, Student)

Now, if is_student(val) returns True, the type checker knows that val is of type Student. If it returns False, the type checker knows that val is not of type Student.

Generally speaking, you should use it when..

• The function returns a boolean value.

• The function checks an object's type using isinstance() or any other mechanism.

6. Official Support for iOS & Android

Python 3.13 is going to have a separate official release for the iOS platform. The team is working on the Android one as well, but not planned for the 3.13 release.

7. Version Support

• Python 3.9 - 3.12 have one and a half years of full support, followed by three and a half years of security fixes.

• Python 3.13 and later have two years of full support, followed by three years of security fixes.

Python 3.14, 3.15, and 3.16 Expected Removals

We're going to see many removals as some components in the standard library are deprecated. Here, I've listed the libraries most affected by these future component removals.

• argparse

• asyncio

• pathlib

• importlib

Conclusion

GIL has been both a blessing and a mess, in my opinion. It's great to see the community moving forward, considering alternatives and solutions for allowing users to optionally use the components. I'm confident that the JIT compiler will make Python even faster in the next few releases. There will be significant performance improvements in high-scale web frameworks like Django. I hope this article has given you a clear insight into the upcoming Python 3.13 release.

What is a Lambda Function?

In Python, a lambda function is a small function defined using the lambda keyword. The syntax for a lambda function is straightforward:

lambda arguments: expression

• Arguments: The input parameters to the function.

• Expression: The single expression that is evaluated and returned by the function.

A simple example is:

add = lambda x, y: x + y
print(add(2, 3))  # Output: 5

Here, lambda x, y: x + y creates a function that takes two arguments, x and y, and returns their sum.

This simple lambda function is equivalent to the following def function in Python:

def add(x, y):
    return x + y

When to Use Lambda Functions?

Lambda functions are best used in scenarios where a small, simple function is required temporarily, especially when passing functions as arguments to higher-order functions like map() and filter().

Common Use Cases

1. Using Lambda with map():

    numbers = [1, 2, 3, 4]
    squared = list(map(lambda x: x ** 2, numbers))
    print(squared)  # Output: [1, 4, 9, 16]
   

2. Using Lambda with filter():

    numbers = [1, 2, 3, 4, 5, 6]
    evens = list(filter(lambda x: x % 2 == 0, numbers))
    print(evens)  # Output: [2, 4, 6]
   

3. Using Lambda with sorted():

    points = [(2, 3), (1, 2), (3, 1)]
    sorted_points = sorted(points, key=lambda point: point[1])
    print(sorted_points)  # Output: [(3, 1), (1, 2), (2, 3)]
   

Best Practices for Using Lambda Functions

While lambda functions can be a powerful tool, they are not without their limitations and potential pitfalls. Following best practices can help you avoid common issues.

1. Keep Lambda Functions Simple: Lambda functions should be simple and concise. If the function requires more than one expression or is complex, it's better to use a standard function defined with def.

    # Good
    increment = lambda x: x + 1
   
    # Bad
    complex_lambda = lambda x: (x + 1, x ** 2)  # Better as a regular function
   

2. Use Descriptive Names: When assigning lambda functions to variables, use descriptive names to indicate the purpose of the function. Just like a normal function.

    multiply_by_two = lambda x: x * 2
   

3. Avoid Overusing Lambda Functions: While lambda functions can make code more concise, overuse can lead to code that is difficult to read and maintain. Use them judiciously and prefer regular functions when the logic is complex.

4. Use Lambdas in Context: Lambda functions shine when used in context, such as within map(), filter(), or sorted(). If the lambda is being assigned to a variable and used multiple times, consider defining a proper function.

Worst Practices with Lambda Functions

1. Complex Lambda Expressions: A lambda function should only contain a single expression. Using complex logic within a lambda function can make the code unreadable.

    # Bad practice
    func = lambda x: x if x > 10 else x + 10 if x > 5 else x + 5
   

2. Ignoring Readability: Lambda functions can sometimes obscure the meaning of the code, especially if overused or if they contain nested lambdas.

    # Hard to read
    result = (lambda x: (lambda y: x + y)(10))(5)
   

3. Using Lambdas Where def is Clearer: If a lambda function spans multiple lines or performs multiple operations, using a standard function definition is more appropriate.

    # Better as a regular function
    def add_and_square(x, y):
        return (x + y) ** 2
   

Advanced Usage of Lambda Functions

While lambda functions are typically used for simple tasks, there are some advanced use cases where they can be applied creatively and effectively.

1. Lambda with Higher-Order Functions: Lambda functions are often used in conjunction with higher-order functions that take other functions as arguments. It's quite similar to decorators, isn't it?!

    def apply_function(func, value):
        return func(value)
   
    result = apply_function(lambda x: x ** 2, 4)
    print(result)  # Output: 16
   

2. Lambda with reduce(): The reduce() function applies a lambda function cumulatively to the items of a sequence.

    from functools import reduce
    numbers = [1, 2, 3, 4]
    product = reduce(lambda x, y: x * y, numbers)
    print(product)  # Output: 24
   

3. Lambda in Key Functions: Lambdas are often used as the key argument in functions like sorted() or min() to determine the sorting or selection criteria.

    names = ['Alice', 'Bob', 'Charlie']
    longest_name = max(names, key=lambda name: len(name))
    print(longest_name)  # Output: Charlie
   

4. Currying with Lambda Functions: Lambda functions can be used to create curried functions, where a function with multiple arguments is transformed into a series of functions each with a single argument.

    def multiply(x):
        return lambda y: x * y
   
    double = multiply(2)
    print(double(5))  # Output: 10
   

5. Using to Define Immediately Invoked Functions (IIFs): Some functions get invoked as they get defined. They are so popular in Javascript. In Python, there is a chance to define these types of functions using lambda functions.

    @lambda _:_()
    def my_iif():
        print("Don't call me. I'm already invoked!")
   

Conclusion

Lambda functions are a versatile and powerful feature in Python, ideal for situations where you need a small, one-off function. While they can lead to more concise code, using them wisely is essential to maintain readability and avoid complexity. Understanding when and how to use lambda functions effectively can enhance your Python programming skills and make your code more expressive and functional.

In this article, I will discuss the steps I take to create a clean and impressive Python repository with over 90% code coverage and an excellent Development Experience (DX).

First, I Ask..

Before I take any steps, I have to ask myself a few questions. Initially, I think about my users and determine who I am releasing the tool for. Am I developing a tool for developers, like a package or library? Or am I working on a service for users with little to no programming knowledge?

Will I be the only developer working on this tool, or will it be open for contributions from developers of all experience levels? Which development flow will I follow?

Regardless of the tools, these are the basic initial questions I ask before starting. Today, we'll explore the steps for creating a sample open-source repository that other developers can contribute to and develop.

We will explore the tools I use, how I use them, and the value they bring to your workspace and repository.

I Use Git & GitHub

There are so many version-controlling software. I prefer Git as GitHub fully supports that. It's also easy to learn for beginners. Also, some other tools on my machine rely on git. So for me, git is the perfect solution.

DX Matters A Lot

Development experience is one of those great feelings that not all open-source contributors get to enjoy when contributing, often due to poor code quality and terrible development flows from some projects.

For some repositories, it takes days to understand the project's flow and build momentum to contribute. On the other hand, there are very neat projects where it only takes a few minutes to find the area you want to contribute to.

It's about documentation, clean code, excellent code structure, and a solid design. These key concepts help you find the issue you want to fix in someone's repository very quickly.

Tips For Improving the Development Experience

As a new contributor, what bothers you the most about a repository you just switched to? What features would you like that new repository to have to make you feel great about returning and contributing even later?

It's very common not to know the entire codebase in a repository. It might even be a framework you want to contribute to, so studying the entire framework and reviewing its codebase is obviously not a good practice. How do you want to know whether your change is healthy and not breaking any other part of the codebase?

In the next sections, we'll explore tools and best practices to help you maintain a clean, solid Python repository that every developer would love to open pull requests on.

Testing & Code Coverage

In the open-source world, you don't know much about your contributors' expertise levels. That's why reliability is crucial. Testing every change in your repository helps ensure your code's reliability. While it's not a perfect solution, it will catch many issues and vulnerabilities at the right time.

It doesn't really matter which development flow you follow, whether it's TDD or DDD, or if you write tests after your components are working. Make sure all related components are tested with each change.

Now, whenever someone makes a change in your repository on their local machine, they can test that change by running a single command to ensure everything is fine and the codebase is still working as expected.

He doesn't have to test every part of the project, and neither do you. But how do I achieve this in my repositories?

In a Python repository, I usually use either the standard unittest library or PyTest, which is an excellent tool for writing unit tests.

On top of that, I use Coverage.py to check how much of my code is covered by tests. It's not the smartest solution, but it works well for small to medium-sized projects.

If you want to use a third-party tool with more options, details, and great accessibility in your repository, CodeCov is a good solution for your Python projects.

Linting & Formatting

I don't think it needs any additional explanation on how important linting and formatting are. So, hands down, Ruff is the best tool for maintaining consistent formatting and linting across your entire repository. I love this tool because it handles all the cleaning tasks, so you won't need any other tools. Most of the time, I find myself ignoring some PEP statements, but that's fine.

How do I make the contributors to use Ruff and deliver their changes formatted and linted? Well, it's described in the next section.

I Use Pre-commit For Automate Evaluations

Pre-commit is essentially a Git Hook that runs automatically with each git commit by default. How does it help with open-source maintenance?

I use pre-commit to run Ruff and check the format and lint of any changes made by contributors. Actually, I don't run it myself; the contributors use it on their own!

As the maintainer of the repository, all I need to do is add a pre-commit configuration file to the root of my repository. Contributors then have to install pre-commit and enable it. From that point on, commits will only go through if Ruff runs successfully. If Ruff fails, the commit won't happen.

If there are contributors who don't want to install pre-commit and add any hooks to the .git/hooks/ directory, that's still fine. We can set up a CI/CD pipeline to run pre-commit hooks and catch the linting and formatting issues when a PR is opened. We'll discuss that later.

Multiple Python Version Support

There are times when I want my repository to work in environments with different Python versions. Naturally, before any deployment, my project should be tested in all those environments, right?

I use Tox for that purpose. Consider tox as an environment (venv) manager in your repository. You can define the following environments and set a custom set of commands, it'll create those virtual environments and run those commands.

[tox]
env_list = py3{8,9,10,11,12}
skipsdist = true
skip_install = true

[testenv]
description = run tests
deps = -rdev_requirements.txt
commands =
    coverage run -m pytest {posargs:tests}
    coverage report -m
    coverage erase

This is a very basic tox.ini config file. It shows that I have five environments: py38, py39, py310, py311, and py312. For all these environments, the following process will occur.

1. Tox creates the environment.

2. Uses pip to install the dependencies described like -r dev_requirements.txt.

3. Runs coverage run -m pytest {posargs:tests}

4. Runs coverage report -m

5. Runs coverage erase

This procedure happens for each environment, meaning we should expect tox to be executed five times.

There is a cool fact about Tox. It creates virtual environments for each environment defined inside the tox.ini file. Running the tox command goes through the process, so if you've already run that command, you should have a .tox/ directory in the root of your project, containing all the environments.

.tox/
├── py38/
├── py39/
├── py310/
├── py311/
└── py312/

It makes the further tox calls way faster because the dependencies are already installed in the environments. Note that if you want to test your changes in all these environments, you should have all these Python versions installed on your machine so that Tox can create those environments and test your changes. I use pyenv for that purpose.

CI/CD Pipelines

What if the contributors forget to install pre-commit or run tox to make sure their changes are tested in all supported environments and don't break anything in the repository?

Well, we need to double-check and ensure everything happens correctly. Since I'm developing my repository on GitHub, I use GitHub Actions. Almost all open-source repositories follow the Fork Flow strategy for contributions. This means if you want to contribute to someone's repository, you first need to clone it, make your changes, and then open a pull request.

As a maintainer, you can run both tox and pre-commit inside those pull requests. But wait a second. Why not use pre-commit inside a new tox environment? That way, your pipeline would be easier to follow. If any contributor regrets using pre-commit, it's still part of the tox configuration.

[tox]
env_list = py3{8,9,10,11,12}, pre-commit   # <- new
...

[testenv:pre-commit]
description = run pre-commit
deps = pre-commit
commands = pre-commit run --all-files --show-diff-on-failure

Now, our tox has six environment and in the last environment, it first installs pre-commit and then runs pre-commit run --all-files --show-diff-on-failure. Nice!

There is a useful feature of Tox that I forgot to mention earlier. When you run tox, it only runs the environments for which you have the corresponding Python interpreter version installed on your machine. What does that mean?

If you only have Python 3.8 installed and you run tox, only one environment will be created, and the codebase will be tested in that environment. Tox won't return any status code other than 0 if you don't have the other Python versions installed. That's great.

I use matrix in my actions pipeline to run tox for each Python environment.

name: Testing

on:
  pull_request:
    branches: [main]

jobs:
  Testing:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python: ["3.8", "3.9", "3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

      - name: Install tox
        run: pip install tox

      - name: Run tox
        run: tox -e py

Now, whenever someone opens a new pull request, a pipeline will get triggered and test the changes in all the environments.

We're almost there. The next section is optional. If you want to include documentation for your Python repository, then don't skip it.

Documentation

I've used Sphinx with reStructuredText (rST) format before. It's a good solution if you want to add quick documentation. You can gather and display information about internal APIs effectively.

You can then deploy your documentation on ReadTheDocs for free. But if you're looking for more customization and flexibility, my best advice would be MkDocs.

Material MkDocs has taken the project further by adding more flexibility, color options, and visual plugins. Both MkDocs and Material MkDocs support Markdown, which can speed up your workflow if you're not familiar with rST.

See in Practice

If you want to see all the tools and practices described in this article in action, I highly recommend checking out this repository of mine.

Conclusion

In conclusion, adopting best practices and utilizing tools to maintain Python repositories not only enhances developer experience (DX) but also contributes to the overall efficiency and quality of the software development process. By prioritizing simplicity, clean code, and thoughtful design decisions, developers can streamline their workflows, reduce technical debt, and foster a collaborative and inclusive development environment. Embracing these principles not only benefits the individual developer but also the entire team and the long-term success of the project.

Ultimately, investing in maintaining clean and well-organized code will pay off in the form of increased productivity, easier maintenance, and more robust and resilient software applications.

I believe we all agree that wisdom is the most valuable thing anyone can have over time. We've always been told by our parents, school, and society that books are the real deal. They are pure valuable knowledge in your hands. But why? Is it true? If it is, then why are we so obsessed with other types of learning, such as watching tutorials, videos, and podcasts?

Why do we find reading frustrating? Is it really is or we've changed over time and our brain presumes that it's a boring activity?!

Let's find out how you can hack your mind and unlock its full potential when it comes to reading!

Understanding the Mechanics of Reading

Reading is a complex process involving the coordination of various ocular movements and cognitive functions. Two key components of eye movements in reading are fixations and saccades. Fixation refers to the moment when our eyes pause on a specific point in the text, allowing the brain to process the information. These pauses typically last between 200 to 300 milliseconds. During fixation, the visual information is sent to the brain for decoding and comprehension.

Saccades are the rapid movements our eyes make between fixations. These jumps can range from a few characters to several words, depending on the reader's proficiency and the complexity of the text. Saccades occur in approximately 20 to 40 milliseconds. The efficiency of these movements significantly impacts reading speed and comprehension. Inefficient saccadic movements can lead to slower reading and reduced comprehension as the brain struggles to keep up with the visual input.

Eye Tracking and Reading Patterns

Eye-tracking technology has provided valuable insights into reading patterns and behaviors. By monitoring where and how long a reader's gaze rests on a page, researchers can analyze the efficiency of their reading process. Eye-tracking studies have revealed that proficient readers exhibit more efficient saccadic movements and shorter fixation durations compared to less skilled readers. These insights have informed the development of bionic reading methods aimed at optimizing these ocular movements.

The Brain's Role in Reading

The brain plays a crucial role in reading, and decoding visual information into meaningful language. This process involves multiple regions of the brain working in concert. The primary visual cortex processes the raw visual input, while the fusiform gyrus, particularly the Visual Word Form Area (VWFA), specializes in recognizing letters and words. Once recognized, the brain's language centers, including Broca's and Wernicke's areas, work to decode and comprehend the text.

Research has shown that our brain does not read every letter in a word sequentially. Instead, it uses contextual clues and pattern recognition to interpret words quickly. This phenomenon, known as the "word superiority effect," allows the brain to recognize words as whole units rather than individual letters. This ability underpins the effectiveness of bionic reading methods, which leverage the brain's capacity for rapid word recognition.

The Importance of Context

Context plays a vital role in reading comprehension. The brain uses surrounding words and prior knowledge to predict and infer meaning, reducing the cognitive load required to decode each word individually. This predictive processing enables faster and more efficient reading. Bionic reading methods enhance this natural ability by presenting text in a way that highlights key information, aiding the brain's predictive and inferential processes.

The Psychological Aspects of Reading

Reading involves significant cognitive load, as the brain must decode visual information, access stored knowledge, and integrate new information into existing mental frameworks. High cognitive load can impede reading speed and comprehension. Bionic reading methods aim to reduce cognitive load by optimizing the presentation of text, making it easier for the brain to process information.

One psychological concept relevant to reading is "cognitive ease." When information is presented in a way that aligns with our brain's natural processing capabilities, it feels easier to understand and remember. Bionic reading methods exploit this by structuring text to align with our brain's strengths, enhancing cognitive ease and improving reading efficiency.

Motivation and Engagement

Motivation and engagement are critical factors in reading success. Readers who are motivated and engaged with the text are more likely to comprehend and retain information. Bionic reading methods can enhance engagement by making reading feel less effortful and more rewarding. By reducing the strain associated with traditional reading, these methods can help maintain motivation and sustain attention over longer periods.

Bionic Reading Methods

There are several methods to convert text into its bionic version, and in almost every solution, you are free to apply whatever convention you think will work best for you. We're about to showcase them here.

Highlighting Key Information

One of the fundamental principles of bionic reading is the strategic highlighting of key information. By emphasizing important words or phrases, bionic reading methods guide the reader's focus and facilitate faster comprehension. This technique leverages the brain's ability to recognize words as whole units and enhances the efficiency of fixation and saccadic movements.

Chunking and Text Formatting

Chunking refers to breaking down text into manageable units, or chunks, to improve readability. This method is based on the idea that the brain can process chunks of information more efficiently than individual letters or words. By organizing text into grammatical chunks, bionic reading methods reduce cognitive load and make it easier for the brain to decode and comprehend information.

Text formatting is another crucial aspect of bionic reading. This includes adjusting font size, spacing, and line length to optimize readability. Studies have shown that certain fonts and text arrangements can enhance reading speed and comprehension. Bionic reading methods often incorporate these findings to create text formats that align with the brain's natural processing abilities.

The Role of Technology

Technology plays a significant role in implementing bionic reading methods. Digital platforms and applications can dynamically adjust text presentation to suit individual reading preferences and needs. Eye tracking technology, for example, can be used to tailor text formatting in real time, providing a personalized reading experience that maximizes efficiency and comprehension.

Are Partial Words Enough?

One intriguing aspect of bionic reading is the question of whether only a few letters of each word are sufficient for comprehension. Research suggests that the brain can indeed recognize words even when parts of them are obscured or altered, as long as the first and last letters remain intact. This phenomenon is known as "typoglycemia." For example, the sentence "Aoccdrnig to a rscheearch at Cmabrigde Uinervtisy" can still be understood despite the jumbled letters.

Bionic reading methods can exploit this by selectively highlighting or modifying parts of words to enhance readability without compromising comprehension. By presenting just enough information for the brain to recognize and process words, these methods can significantly speed up reading.

What is Sighted?

Sighted is an AI-powered solution to improve reading quality with the help of NLP and bionic algorithms.

Read this article to find out more about Sighted!

Case Studies and Applications

Educational Settings

In educational settings, bionic reading methods have shown promise in improving reading speed and comprehension among students. By reducing cognitive load and enhancing engagement, these methods can help students process information more efficiently, leading to better academic performance.

Professional Environments

Professionals who need to process large volumes of text, such as lawyers, researchers, and journalists, can benefit from bionic reading methods. By optimizing reading efficiency, these methods can save time and improve productivity, allowing professionals to stay on top of information without sacrificing comprehension.

Accessibility

Bionic reading methods also hold the potential to enhance accessibility for individuals with reading difficulties, such as dyslexia. By presenting text in a way that aligns with the brain's natural processing capabilities, these methods can make reading more accessible and less challenging for those with cognitive impairments.

Conclusion

Bionic reading methods represent a significant advancement in our understanding and enhancement of the reading process. By leveraging the brain's natural abilities and optimizing ocular movements, these methods can significantly improve reading speed and comprehension. The integration of psychological insights, such as cognitive load and motivation, further enhances their effectiveness. As technology continues to evolve, the potential for personalized and adaptive bionic reading solutions will only grow, offering exciting possibilities for readers of all backgrounds and abilities.

The implementation described in this article is live hosted on GitHub.

You can use it with GitHub's official action/cache action to cache your action's dependencies. This is helpful when working with environments that have many or large dependencies that take time to load. This way, you can quickly get TensorFlow running inside your pipelines! We're not going to use it today though as our action is quite light and fast in terms of response.

In this article, we'll create a new action using PyAction that triggers when an issue is opened or reopened. It will read the issue data, use Sighted to analyze the text in the issue form, and finally, display the result as a comment based on the analysis.

Installation

Let's install both pyaction and sighted. They both require you to have pip and Python >= 3.8 installed.

pip install "pyaction[cli" sighted

To get started, we use the init command in pyaction to provide a base template for our action.

pyaction init

🎤 Action name
   Sighted Action
🎤 Action's slug
   sighted-action
🎤 Short description
   Turning your issue content into bionic text
🎤 Author's name
   Sadra Yahyapour
🎤 Include workflow testing pipeline
   Yes

Change the current directory to the action's path.

cd sighted-action/

Development

We need to interact with the repository issues meaning we need to have access to the issue ID. Our action doesn't have any user-related inputs. Let's start with the action.yml file. I need to add one input and one output.

inputs:
  ...
  issue_number:
    description: The id of the issue
    required: true

outputs:
  bionic_text:
    description: The converted bionic text

Leave the rest of the file as it is. Add the moment, we're using sighted==0.0.4. Add it to the requirements.txt file.

...
sighted==0.0.4

Create .github/ISSUE_TEMPLATE/sighted_text.yml file. It contains the structure of the issue template.

name: Sighted Text
description: Using Sighted to convert your input into Markdown bionic text
title: "Sighted: Bionic Text"
body:
  - type: textarea
    attributes:
      label: Text
      description: Write or paste your text here
    validations:
      required: true
  - type: dropdown
    id: color
    attributes:
      label: Color
      description: Set the color for fixations
      options:
        - Gray
        - Light Gray
        - Dark Gray
        - Red
        - Yellow
        - Green
      default: 1
  - type: dropdown
    id: fixation
    attributes:
      label: Fixation
      description: Set the fixation
      options:
        - 1
        - 2
        - 3
        - 4
        - 5
      default: 1
  - type: dropdown
    id: saccade
    attributes:
      label: Saccade
      description: Set the saccade
      options:
        - 1
        - 2
        - 3
        - 4
        - 5
      default: 0

Issue template allows you to design a form and force users to fill the form if they want to open any issue on your repository. The above template would create something like this in the issues tab.

We're almost there. All we need to do is to implement the actual action and make it usable by completing the .github/workflows/test.yml pipeline.

Open the main.py file and import the following sighted components.

from string import Template               # new

from pyaction import PyAction
from pyaction.auth import Auth            # new
from pyaction.issues import IssueForm     # new
from sighted import Literal               # new
from sighted.language import PoS          # new

Notice we're importing pyaction.auth.Auth and pyaction.issues.IssueForm. We need the IssueForm class to pass it an Auth object and interact with the issues.

We're going to use LaTeX to colorize text in GitHub's markdown platform. You probably know, there is no way you could colorize a text in your markdown unless you use LaTeX. That's not a common way, but for the sake of experiments, that's fine.

For that matter, we need this const variable defined.

...
COLORS = {
    "Gray": "{gray}",
    "Light Gray": "{lightgray}",
    "Dark Gray": "{lightgray}",
    "Red": "{red}",
    "Yellow": "{yellow}",
    "Green": "{green}",
}

Let's focus on the main function. Consider this one.

...
workflow = PyAction()

@workflow.action()
def my_action(github_token: str, repository: str, issue_number: int) -> None:
    auth = Auth(token=github_token)

    repo = auth.github.get_repo(repository)
    user_input = IssueForm(repo=repo, number=issue_number).render()

    language = Literal(
        text=user_input["Text"],
        fixation=int(user_input["Fixation"]),
        saccade=int(user_input["Saccade"]),
        ignore_pos=[PoS.PUNCT],
    )

    color = COLORS[user_input["Color"]]
    prefix, postfix = f"$`\color{color}", "`$"

    transformed_text = language.transform(
        template=Template(f" $`$fix`$${prefix}$unfix{postfix}")
    )

    workflow.write({"bionic_text": "".join(list(transformed_text))})

It first reads the issue. Serializes that and takes Text, Fixation, Saccade, and Color. Then it creates prefix and postfix based on the color. Finally, the whole bionic transformed content will be returned under the variable name of bionic_text.

Open the .github/workflows/test.yml. Paste the following workflow steps.

name: Testing

on:
  issues:
    types: [opened, reopened]

jobs:
  Test:
    runs-on: ubuntu-latest
    name: Testing the action
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Create processing comment
        uses: peter-evans/create-or-update-comment@v4
        id: comment
        with:
          issue-number: ${{ github.event.issue.number }}
          body: Processing..

      - name: Running the action
        uses: ./
        id: sighted
        with:
          issue_number: ${{ github.event.issue.number }}

      - name: Update comment
        uses: peter-evans/create-or-update-comment@v4
        with:
          comment-id: ${{ steps.comment.outputs.comment-id }}
          body: ${{ steps.sighted.outputs.bionic_text }}
          reactions: rocket
          edit-mode: replace

It gets triggered whenever an issue gets opened or reopened. Creates a comment in the issue form. Runs the action. Updates the comment that it just created. Here is the result.

Hopefully, you enjoyed this practice!

Conclusion

In this article, we created a GitHub Action using PyAction that triggers when an issue is opened or reopened, reads the issue data, uses Sighted to analyze and transform the text into bionic text, and displays the result in a comment. We walked through the installation, setup, and development process, including defining inputs and outputs, creating an issue template, implementing the main functionality with Python imports, and setting up a GitHub workflow to automate the process.

1. The Zen of Python

One of the most famous Easter eggs in Python is the "Zen of Python," a collection of guiding principles for writing computer programs. These aphorisms were written by Tim Peters and can be displayed by importing the this module.

import this

Upon executing this code, you'll be greeted with the Zen of Python:

The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Devs are sometimes good philosophers. Check this out.

>>> import this
>>> love = this
>>> this is love
True
>>> love is True
False
>>> love is False
False
>>> love is not True or False
True
>>> love is not True or False; love is love
True

Poetic. Isn't it?!

2. Importing Antigravity

Python takes you on a literal journey when you import the antigravity module. This Easter egg references a famous XKCD comic strip about Python.

import antigravity

Executing this code opens your web browser and takes you to the XKCD comic about Python:

3. The Walrus Operator

Introduced in Python 3.8, the walrus operator (:=) allows assignment expressions. The fun part is that it's named after it resembles the eyes and tusks of a walrus.

if (n := len('walrus')) > 5:
    print(f"The length of 'walrus' is {n}")

Output:

The length of 'walrus' is 6

4. Barry's Eggs

There's a quirky Easter egg that references Barry Warsaw, one of Python's developers. By using the from __future__ import barry_as_FLUFL statement, you can enable an alternative form of assignment using the <> operator, reminiscent of the older days of Python.

from __future__ import barry_as_FLUFL

# This will work with the import above
2 <> 3

Output:

True

But if you do this, it'll raise an exception.

2 != 3
# SyntaxError: with Barry as BDFL, use '<>' instead of '!='

5. Hello, World!

The classic "Hello, World!" program has a playful twist when using the __hello__ module.

import __hello__

Output:

Hello world!

Whenever you install Python in a fresh environment, you can also do this to ensure your Python setup process is successful.

$ python -c "import __hello__; __hello__.main()"
Hello world!

6. Braces in Python

Python's design philosophy famously excludes the use of braces ({}) for code blocks, preferring indentation instead. However, there's an Easter egg that humorously acknowledges this design choice.

from __future__ import braces

Instead of enabling braces, this code raises a SyntaxError with the message "not a chance."

Output:

  File "<stdin>", line 1
    from __future__ import braces
                                  ^
SyntaxError: not a chance

I guess we'll never see anyone using braces in Python ever.

7. Time Travel with timeit

The timeit module is used for timing the execution of small code snippets. But did you know it also contains a cheeky reference to "time travel"?

import timeit

timeit.timeit('"-".join(str(n) for n in range(100))', number=10000)

Output:

0.28043669999999996

While this example shows the normal use of timeit, the module's documentation contains whimsical references to time travel, such as "If you can time travel, then you're doing it wrong."

8. Python Philosophy

Python's import this reveals the Zen of Python, but there's also another philosophical Easter egg when you try to import __phello__.

import __phello__.world

Output:

Hello world!

This playful module echoes the traditional "Hello, World!" while embedding it in a mysterious, underscore-laden package name. Somehow similar to import __hello__.

9. Swapping Values

Python allows for elegant value swapping without a temporary variable. While not strictly an Easter egg, this feature often surprises newcomers.

a, b = 1, 2
a, b = b, a
print(a, b)

Output:

2 1

10. Exception Thrower

In Python 3.9, __peg_parser__ would throw a syntax error with a certain message of "You found it!".

>>> __peg_parser__
  File "<stdin>", line 1
    __peg_parser__
    ^
SyntaxError: You found it!

Conclusion

Python's Easter eggs add a layer of charm and character to the language, reminding us that programming can be both a serious and fun endeavor. These hidden gems not only showcase the creativity of Python's developers but also invite us to explore and enjoy the lighter side of coding. Whether you're a seasoned Pythonista or a curious newcomer, these Easter eggs are sure to bring a smile to your face and a deeper appreciation for the delightful intricacies of Python. Happy coding!

• Sighted is LIVE here!

Distraction. A very familiar term in recent decades. The Internet has been a blessing for humanity, but it has also caused several issues. When was the last time you managed to finish a book? How did it go? Have you noticed any difference between reading today and reading in 2000? How engrossed in a book are you today compared to before?

In this article, we'll introduce an AI-powered solution to improve reading quality. This is not just a basic introduction or a project demo. I'll guide you through all the decision-making phases I went through during the development of this project.

Problem

I had ADHD as a child. My parents always said that there was nothing I could do without rushing. I was like Road Runner (the animation). 😅

Almost all of those behaviors disappeared as I grew up. However, one habit that remains is my inability to stick with books for a reasonable amount of time.

I read a paragraph, then take a break. I get back to it for a few minutes, take another break, and continue this way. Although my every smart device is on DND (Do Not Disturb) mode. I did some research and observed myself in different situations.

I realized that I needed to change myself first, but I had already tried that many times. It didn't seem to work. So, I thought, what if I change the subject? What if I modify the book to make it easier to follow, understand, and finish more quickly?

Then I came up with a concept called "Focus Reading" or "Bionic Reading".

Bionic Reading

Bionic solutions use technology inspired by nature to solve problems. Bionic Reading is one such method, designed to help people read more efficiently. It highlights parts of the text, making it easier for the eyes to follow and understand. By emphasizing key elements, Bionic Reading helps readers process information faster, reducing cognitive load and improving reading speed. This technique benefits those with attention difficulties and anyone wanting to enhance their reading skills and retention.

Usage

Sighted is available as an installable Python package. I designed it to be reusable and easy to install on various instances, making it compatible with front-end frameworks like React and Vue. This approach allows you to use Sighted even on language learning platforms.

Installation

Make sure you have pip and python>=3.8 installed on your computer or instance, then run the following command.

pip install sighted

Sighted comes with a ~12MB pre-trained very efficient model. It's built into the library, so you won't need to download anything extra.

Usage

Create a Python file where we will import the necessary classes and functions.

from sighted import Literal
from sighted.language import PoS

from string import Template

We're using the Literal approach for transforming. Let's create an object.

text = "Hello there. This is an experimental text to showcase \
        how fast you can read with Sighted."

language = Literal(
    text=text, 
    fixation=2,
)

I've defined my text and created the language object, which will be transformed using the pattern I will specify later. Sighted analyzes every character, glyph, and symbol in the given text and applies the chosen pattern to it.

If you want to ignore certain parts of speech in the text, use the PoS enum, which includes almost all necessary parts of speech. In our example, I'm going to ignore all punctuation marks (period, comma, apostrophe, quotation, question mark, exclamation mark, brackets, braces, parentheses, dash, hyphen, ellipsis, colon, and semicolon).

language = Literal(
    text=text, 
    fixation=2,
    ignore_pos=[PoS.PUNCT]   #  <-- new
)

I'll discuss saccade and fixation later, but for now, let's focus on the transformation process.

transformed_text = language.transform(
    template=Template(' <span class="$pos" id="$dep"><b>$fix</b>$unfix</span>')
)

I'm using the native string.Template for template definition because Sighted can safely insert information into it. For each word in my text, I'm transforming it into a <span /> HTML tag.

• $fix : The fixed (bold) part of the word.

• $unfix : The part of the text that shouldn't be bolded.

• $pos : Part of speech of the word in the text.

• $dep : Syntactic dependency of the word in the text.

The transformed_text is an iterable object. If I loop over it and print what it contains, I'll get this result.

<span class="intj" id="ROOT"><b>He</b>llo</span>
<span class="adv" id="advmod"><b>th</b>ere</span>
. <!-- Look how this punctuation is ignored -->
<span class="pron" id="nsubj"><b>Th</b>is</span>
<span class="aux" id="ROOT"><b>i</b>s</span>
<span class="det" id="det"><b>a</b>n</span>
<span class="adj" id="amod"><b>exper</b>imental</span>
<span class="noun" id="attr"><b>te</b>xt</span>
<span class="part" id="aux"><b>t</b>o</span>
<span class="verb" id="relcl"><b>show</b>case</span>
<span class="space" id="dep"><b>    </b>    </span>
<span class="sconj" id="advmod"><b>ho</b>w</span>
<span class="adv" id="advmod"><b>fa</b>st</span>
<span class="pron" id="nsubj"><b>yo</b>u</span>
<span class="aux" id="aux"><b>ca</b>n</span>
<span class="verb" id="ccomp"><b>re</b>ad</span>
<span class="adp" id="prep"><b>wi</b>th</span>
<span class="propn" id="pobj"><b>Sig</b>hted</span>
. <!-- Look how this punctuation is ignored -->

Notice the class attributes as well as all the IDs. If I place this result within a <p /> tag inside a very basic HTML structure, you'll get something like this.

Styling

With a little bit of styling, you can have control over each and all parts of speech and dependencies in your text.

/* unfixed letters */
p { color: gray; }

/* fixed letters */
b { color: black; }

/* adverbs */
.adv { border-bottom: solid 1px; }

/* pronouns */
.pron { color: red; }
.pron > b { color: purple; }

/* verbs */
.verb {
    background-color: yellow;
    padding: 3px;
    border-radius: 2px;
}

Terminal usage

It's not just about HTML. You can use any template as the input for the transformer function. See how I've used this feature to display bionic outputs in my terminal!

from string import Template

from rich.console import Console
from rich.markdown import Markdown

from sighted import Literal
from sighted.language import PoS

console = Console()
text = "Hello there. This is an experimental text to showcase how fast you can read with Sighted."

language = Literal(
    text=text,
    fixation=2,
    ignore_pos=[PoS.PUNCT],
)

template = Template(" **$fix**$unfix")
transformed_text = language.transform(template)

md = Markdown("".join(list(transformed_text)))

console.print(md, style="white dim")

Fixation & Saccade

This parameter indicates how many letters from the beginning of each word should be considered as fixation ($fix). It's a value between 1 to 5. As you increase it, you see that the amount of fixed letters will increase from the beginning of each word.

As I mentioned, I needed to determine the fixation formula. For each word length, I selected ten words and examined the fixation on them. Each fixation value should correspond to any word length.

$$L = \begin{cases} 1 & \text{if } W = 2 \text{ or } W < 2 \\ \min\left(\left\lceil \frac{W \cdot F}{5} \right\rceil, W\right) & \text{if } W \geq 3 \end{cases}$$

For words with a length of one or two, only the first letter is bolded. For words longer than three letters, the bottom equation will be considered.

Saccades are rapid, involuntary eye movements that play a crucial role in reading by allowing the eyes to jump quickly from one word or section of text to another.

This attribute reduces the cognitive load on the brain by making it easier to recognize and process words, thereby improving reading speed and comprehension.

If you want to know more about saccade, I highly recommend watching this video on YouTube.

Sighted Helps with ADHD & Dyslexia

By presenting the text with one highly styled word at a chunk of space and controlled saccade and fixation, Sighted helps reduce visual distractions and improves focus.

• Improved focus and attention: By controlling the pace at which text is bolded, Sighted helps individuals with ADHD maintain focus and avoid distractions.

• Reduced visual stress: The controlled presentation of text reduces the visual overload experienced by individuals with Dyslexia, making it easier for them to process and comprehend information.

• Enhanced reading comprehension: It can help individuals with Dyslexia and ADHD improve their reading speed and comprehension by minimizing cognitive load and maximizing text accessibility.

Development Process

This section covers the decisions I made during the development of this project. I don't see myself as a nerd, but I hope this gives you a clear idea of the process.

Day 1 - Starting

I discovered that social media has caused teens, including myself, to lose their connection with books. This might be due to the problems social media caused us. So, I came up with the idea.

• Researching the idea, use cases, and similar projects.

• Finding out, how it can solve a problem and who can benefit from it.

• Thinking about the possible ways that the idea can be delivered.

• How useful the idea is going to be. Is it even implementable?!

Day 2 - Researching

I was already familiar with tokenization, literal processing, and literature to some extent. I knew some frameworks and libraries, so diving deeper into this process wasn't a big deal for me. Instead, I focused on the tools and explored how they could benefit me.

• Learned about some keywords in this specific field.

  • Learned about terms like fixation, saccade, lemmatization, eye tracking, and how the human brain processes text. I also worked on a formula that calculates the fixation for each word based on its importance in the context of the sentence.

Day 3 - Feedback

Well, I couldn't rely solely on my own thoughts as a customer since I won't be the only user of this service. So, I made some parts public and shared a short teaser on socials to gauge the crowd's interest. Turned out they loved it so I kept developing.

I also tried the same technique on RTL and cursive-written languages, but it was not as effective as in English.

• Deployed a very basic MVP and asked some friends for feedback.

• Shared a teaser clip on socials to see the people's reaction.

Day 4 - Branding

Branding matters, especially for my idea, which was going to be a Python package, a website, and a repository. It needed to be unique. I asked ChatGPT for some help and ultimately chose "Sighted" because it comes from "Sight" which is a fitting word in the world of biology.

• Choosing a brand name, slogan, logo design, and theming.

Day 5 - Deployment 🎉

Last but not least, I hit the big green button to deploy everything on the cloud. There were a few minor issues to fix, but nothing too serious. I made it through.

Hopefully, this section has given you a clear understanding of what a hackathon submission journey may look like!

Tech Stacks

For the website, I used React (TypeScript) with Aceternity UI and Shadcn UI for the UI part deployed on Vercel.

I used Python and SpaCy for the package development.

Useful Links

• Website -> https://sighted.vercel.app

• Website repo on GitHub -> https://github.com/lnxpy/sighted-web

• Package -> https://pypi.org/project/sighted

• Package repo on GitHub -> https://github.com/lnxpy/sighted

Hashnode + Bionic Reading

What if Hashnode could publish articles in bionic mode? Let me know what you think about this cool effective feature!

Conclusion

In conclusion, bionic technology offers a groundbreaking solution for individuals struggling with reading difficulties. By harnessing the power of bionic reading with AI (NLP), these individuals can access a more efficient and accessible means of consuming written content. The future of bionic reading holds significant promise in revolutionizing how we interact with written text, offering a beacon of hope for those seeking a more enriching and fulfilling reading experience.

As GitHub says..

Actions are individual tasks that you can combine to create jobs and customize your workflow. You can create your own actions, or use and customize actions shared by the GitHub community [aka Marketplace].

In this article, we will demonstrate a simple implementation using PyAction, a tool that allows you to create actions using Python. This way, you can take advantage of Python libraries and bring your ideas to pipelines!

Additionally, we will discuss the recent release of PyAction and the new features that have been introduced in version 0.6.x.

Actions in a Nutshell

In the following example, you see a simple pipeline in GitHub Actions that triggers on the push event and executes the bash script echo Hello world!. You can place any bash script there to run, including an API call using curl maybe!

name: CI Example

on:
  push:
    branches: [main]

jobs:
  Builder:
    runs-on: ubuntu-latest

    steps:
    - name: Greeting
      run: echo Hello world!

We have a Builder job with just one step, which is executing a shell script. Actions are like functions. Considering the earlier example, what if you wanted to send an email instead of running a bash script?!

    ...
    steps:
    - name: Sending email
      run: python send_email.py # hmm.. let's see.

Well, thanks to Dawid Dziurla, there is already an action designed for this purpose. You can modify your pipeline to use it in this manner.

    ...
    steps:
    - name: Send mail
      uses: dawidd6/action-send-mail@v3
      with:
        subject: Github Actions job result
        to: someone@somewhere.com
        from: Sadra Yahyapour
        body: CI workflow executed successfully!

As you can see, we are now using the dawidd6/action-send-mail release v3 action with certain input parameters (subject, to, from, and body).

The aim here is to introduce a solution for creating actions using Python and have the ability to call it with the desired input parameters.

Worth noting that the action-send-email is written in JavaScript and we're talking snakes here. 🐍

Creating an Action

Technically, GitHub offers three ways to develop custom actions.

• JavaScript actions

• Docker container actions

• Composite actions

Let's focus on the Docker container and Composite options. Composite actions are actions created using only bash scripts. Essentially, you have the freedom to perform various tasks within a Composite action. You can compile and execute C programs, install tools based on the optionally-limited runs-on image, make API calls, and more. In essence, Composite actions offer flexibility.

On the other hand, Docker container actions are restricted to the base image specified in the Dockerfile. You can then add additional layers. PyAction follows the Docker container approach and runs your action within a python:3-slim environment. This is what PyAction uses to run your Python actions.

Using PyAction

PyAction is delivered as a third-party package needed for your action to function. Despite this, it is very stable in the local environment for testing. Therefore, you can use it on your local machine easily and even test your action before deploying it.

Installation

Make sure you have pip and python>=3.8 available on your machine and run the following command to install pyaction.

pip install -U "pyaction[cli]"

Creating a base template

It is highly recommended to use the init command to generate a base template for your action. You can then build your action on top of this structure by answering some questions.

pyaction init

This prompting would give us the following action tree.

sms-action/
├── Dockerfile
├── README.md
├── action.yml
├── main.py
└── requirements.txt

1 directory, 5 files

Hello world example

Let's take a look at a simple hello-world example created with PyAction. The goal is to set up an input parameter for users to send their names, and then we will greet them!

After you've initialized the template using the init command, it's time to define the input/output parameters. Open the action.yml file to declare them.

...
inputs:
  name:
    description: user's name
    default: World

outputs:
  phrase:
    description: greeting message

Open the main.py file. And create the very basic greeting_action inside it.

from pyaction import PyAction


workflow = PyAction()

@workflow.action()
def greeting_action(name: str) -> None:
    workflow.write(
        {
            "phrase": f"Hello {name}!"
        }
    )

As you can see, the greeting_action takes one parameter called name which is a string. It also writes to the workflow the variable phrase. We've defined them both in the action.yml file.

Testing

To test if the action works as expected, there is a run command that does the job for us. However, before we proceed with the execution, we need to simulate how action runners invoke the actions with the defined input parameters.

Create a .env file inside the action to simulate the input parameters of the action.

INPUT_NAME=Sadra

Now, by running the run command, you'll see the variables that the workflow.write() method writes to the workflow.

pyaction run
phrase=Hello Sadra!

The phrase variable is accessible in other steps of the user's workflow.

    ...
    steps:
    - name: Greeting action
      id: greeting
      uses: you/greeting-action@main

   steps:
    - name: Showing the message
      run: echo ${{ steps.greeting.outputs.phrase }}

Publishing

To publish the action on the marketplace, you need to consider certain things during the development process. After developing your action, there are some post-development tasks to complete before delivering it to the GitHub Marketplace, such as tagging and releasing it. If you wish to proceed, refer to the publishing in the marketplace section in the documentation.

This hello-world action is also available on https://github.com/lnxpy/pyaction-hello-world. Feel free to check it out! ✨

New Features in v0.6

In the new v0.6 release, a few major features were announced.

Issue Form feature

As GitHub describes the issue forms..

You can define different input types, validations, default assignees, and default labels for your issue forms.

It's a reliable solution for controlling users' input when they open issues on your repositories. By using this feature in PyAction, you can allow users to interact with your actions through the issues tab by filling out the designed form.

For example, take a look at the following repository. It uses the Issue Form feature to serialize the details within the opened issue. It then utilizes this information to invoke MindsDB's mdb.ai service and obtain the output from ChatGPT. Lastly, it comments on the result.

Check out this page for more information about how this feature works.

Running additional bash scripts before invoking the action

If the action requires some additional system dependencies or you want to run some additional commands before the action starts running, you can put all the commands inside a script.sh file inside the action directory. It'll be executed even before your action's Pythonic dependencies installation.

Check out this page for more information.

Local testing

With the run command, test the action locally before publishing your action.

Composite Actions vs PyAction

PyAction uses the Docker container convention to create an isolated environment using DockerHub-hosted images. On the other hand, with a composite approach, you have to go through several steps to set up a Python-friendly environment before implementing your idea.

In a composite action, you often make many external API calls. In contrast, PyAction relies on internal API calls, which are quicker and more secure.

Ultimately, PyAction simplifies local action testing by simulating inputs and outputs.

Useful Links

• PyAction Repository: https://github.com/lnxpy/pyaction

• PyAction Docs: https://pyaction.imsadra.me

• mdb.ai Action (that uses Issue Forms): https://github.com/lnxpy/mdb-ai-prompted-text

Conclusion

GitHub Actions is a platform commonly used for performing CI tasks on projects hosted on GitHub. I developed a tool called PyAction to allow users to create custom actions using Python. PyAction includes a range of features such as local testing.

By the term "advanced," I am referring to the features and functionalities of the database that users can access, like setting up scheduled jobs, auto-indexing, and creating functions/macros and procedures when needed.

We have entered a new era where databases are no longer just for storing data. Developers are utilizing AI-friendly programming languages like Python to build database engines. This method has enabled them to merge AI models with DBMSs.

This article explains some basic concepts about the revolution happening in databases. We won't delve into very deep AI concepts. Providing a brief overview of each topic should suffice to lead us to the main subject: integrating AI and databases, the process involved, and the benefits companies and teams are reaping from it.

This article is based on my research on related concepts, a few months of working as an open-source contributor at MindsDB, and the paper EVA: A Symbolic Approach to Accelerating Exploratory Video Analytics with Materialized Views.

Supervised Learning

In every real-world machine learning scenario, we design a system using a data set. We always have a data source available to us. This data might come from an external stream (like CCTVs, real-time API calls, or pub-sub systems) or be stored in a local database within the same infrastructure.b

Normally, in an AI project, especially in machine learning, we go through three phases. We begin with gathering the necessary data. After accumulating a sufficient amount of data for our model, we proceed to the first phase, which is pre-processing.

Pre-processing: This step initially covers all the necessary operations that need to be done on our essential data to reduce the outliers, scale them, replace the missing records, data correction, and so on.

Now that we have our data prepared, we would typically proceed to the next phase and train a model using this data. When we talk about "training a model based on data", we are referring to developing a mathematical function that takes inputs and provides an output.

$$Predictor(x_1, x_2, x_3,\cdots) = y$$

As a developer, consider this explanation as a function named predict that takes a value and returns the corresponding value from a dictionary for now.

data = {
    10: 3_000,
    15: 5_000,
    20: 10_000,
    25: 15_000,
    30: 20_000
}

def predict(x: int) -> int:
    return data[x]

There is a difference between a mathematical function and a programming function. A function in mathematics provides a result (whether accurate or not) for any input, while in programming, a function might raise an exception during runtime or return nothing (None or null).

We'll see various results if we call this function with different inputs.

predict(20) # 10_000
predict(25) # 15_000
predict(22) # ERROR <KeyError>

Notice how we got an error attempting to call the function with a value that's missing from the data dictionary. The goal is to implement a functionality for the predict() function to predict any value as the key x. Following an approach to convert this programming function works just like a mathematical one. If a 20-square-foot room costs $10,000, then probably a 22-square-foot should cost $11,000.

So far, we've seen a brief preview of how supervised Machine Learning models work. This method is used in lots of forecasting solutions in AI databases.

In the example that we practiced, we were dealing with pure numeric data. In some cases, we might be working with media-typed data such as photos, video tapes, audio, etc.

How does a machine distinguish an apple from a banana? How does a machine classify SUVs out of a road full of taxis? This is where the importance of databases shines and comes in handy in terms of storing vectors and classification.

Integration with Databases

The entire process of reading, restructuring, and purifying the data used to occur on our machine, requiring us to write Python code for these tasks. We needed to assign a table column for our vectors, store the precise parameter values in variables, and so forth. This process could be tedious, particularly in production from a DevOps perspective. That's when we asked: Why not do it in databases?!

In most SQL databases, we have a wide range of options for creating custom macros, functions, and reusable SQL code snippets. That's where we can put our training steps; scientists thought!

Of course, it will make AI more accessible to developers and those interested in integrating AI into their products. However, there is another important reason behind this. In the old classic way, we had to establish the connection between our models and datasets by writing codes. This has changed now, as our models reside within our database tables.

This game-changing solution has two major benefits.

• Easy access to AI models from anywhere.

• Models can reach out to data columns even faster.

With that said, there is also a possibility to use a model based on hand-picket data from the entire dataset using SQL commands and clauses. This feature enables you to quickly evaluate your model's accuracy and tune it in the finest possible way.

How Fast Are They

Technically, when we're talking about numbers and our data is also in numerical form, training a model with this kind of dataset shouldn't be difficult. However, we live in a world where data is diverse. Many things can't be quantified. Can you measure how kind your parents are with a number? Can you express your current mood with a numeric value?

Well, in the sense of numerical values, it's so easy to find a value among all the data. A quick indexing would do the job for you, but how can you find a movie scene among all the movies produced by the industries?!

Imagine you have a table full of photos. Records contain hard-coded URLs that redirect to photos. How can you find the photos that contain an apple in the scene?

We use a method called Vectorizing to create a column that contains the vectorized form of each photo.

Well, mathematically, each photo is a matrice and each cell of that matrice is a vector showcasing the RGB values of that point.

Any type of data can be transformed into numbers (vectors). Your voice consists of frequency pulses, often represented by decibels for loudness and hertz for frequency wave height. Videos are composed of frames, with each frame being a matrix. Texts can also be represented as numbers. The real question is, where do we store the numeric form of our data?!

We used to define a data structure for this, but now, with the assistance of AI databases, we store everything our models require directly within the database that runs our model.

Classification

To find the photos that represent the figure of an apple, we can go on with two solutions.

• Parametrizing

• Vectorizing

Parametrizing: It means we have to tag each photo based on different attributes like color, size, weight, shape, etc, and do the queries based on these values.

Vectorizing: It helps you to define those patterns that we talked about. Their accuracy mainly depends on the quality of the photo.

Conclusion

Hopefully, this article has provided you with a brief overview of the functioning of AI databases, focusing on two key aspects: Parametrizing and Vectorizing.

In essence, understanding the roles of parametrizing and vectorizing is crucial in comprehending how AI databases operate and optimize data processing tasks.

RevAI is a GitHub Action that enables you to create a pipeline on each pull request opened on your repositories. Underneath, it uses MindsDB to handle the requests and LLM interactions.

Case Scenario

Consider someone has branched off a new development line from your repository and has changed a file called file.py. Now, he opens a pull request from him/feature to you/main.

Right when he opens the PR, RevAI gets triggered and starts reviewing his changes.

Ultimately, it leaves a comment that shows what AI thinks about the changes that have been made.

As you can see, during this PR, there was only one file (file.py) that got changed and RevAI has reviewed the file based on the prompt that I had given earlier. We'll go through this process later on.

Customization

As the maintainer of the repository, you have a full control over the factors and criterias that RevAI is going to review the code based on. You can train the model based on any prompting statement that you want. You can also change the commenting template as well.

Setting Up

In this section, we'll talk about the steps that need to be taken to have an instance of RevAI on your own repositories.

1. Create a MindsDB account and train a GPT model

Before we begin..

1. Create an account on OpenAI

2. Create a chatGPT instance

3. Generate an access token from the dashboard and keep it somewhere safe

Log into MindsDB dashboard. Create an instance and run the following SQL snippet.

CREATE MODEL mindsdb.gpt_model
PREDICT response
USING
engine = 'openai',
api_key = '<TOKEN>',
model_name = 'gpt-3.5-turbo',
prompt_template = 'review the {{text}} based on clean-code principles and pep rules then rate it from 1 to 10 and put it in the "score" field. Put your thoughts about it in one sentence in the "message" field.

Respond with no formatting, but in the following structure:

{
    "score": int,
    "message": str
}';

Replace <TOKEN> with your OpenAI token. You can also put whatever prompting statement you want, but in this case, make sure to refer to {{text}} as the source code content inside your prompt and your prompt should end with..

Respond with no formatting, but in the following structure:

{
    "score": int,
    "message": str
}

It's quite obvious that I'm asking AI to review the code and score it based on clean-code principles and pep rules. I assume that it takes only Python files, but you can set any prompting that meets your needs.

2. Set the secrets

Navigate to your repository. Go to Settings > Secrets and variables > Actions. Click on New repository secrets. You need to add two secrets here. One should be named EMAIL that contains your MindsDB's account email and the other one is PASSWORD that is valued to your account's password.

Your repository secrets panel should look like this..

3. Set up the template and workflow

Create .github/comment-template.md file. Put the following markdown snippet as the commenting template.

| 📂 **File**   | 💬 **Comment** | 🏆 **Score**    |
| :-----------: |---------------| :-------------: |
| `{{ .file }}` | {{ .message }} | {{ .score }}/10 |

You can also modify this template and design the structure that you want RevAI to put its thoughts and reviews in.

Don't forget to mention {{ .file }}, {{ .message }}, and {{ .score }} placeholders in your comment-template.md file.

This is a quick look of the template that we designed..

Make a new workflow by creating .github/workflows/review.yml file. Put the following YAML configuration in review.yml file.

name: RevAI Reviewing

on:
  pull_request:
    branches:
      - 'main'

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checking out
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v41

      - name: Use RevAI
        id: revai
        uses: lnxpy/revai@0.1.0
        with:
          email: ${{ secrets.EMAIL }}
          password: ${{ secrets.PASSWORD }}
          files: ${{ steps.changed-files.outputs.all_changed_files }}

      - name: Render template
        id: template
        uses: chuhlomin/render-template@v1.4
        with:
          template: .github/comment-template.md
          vars: |
            file: ${{ steps.revai.outputs.file }}
            message: ${{ steps.revai.outputs.message }}
            score: ${{ steps.revai.outputs.score }}

      - name: Create comment
        uses: peter-evans/create-or-update-comment@v3
        with:
          issue-number: ${{ github.event.number }}
          body: ${{ steps.template.outputs.result }}

This workflow gets triggered whenever someone opens a new pull request to your main branch. To have a brief look at what this workflow does, we can sum them up into a few sequential jobs.

1. It checks out to the commit state where the PR is.

2. Gets a list of changed files.

3. Uses RevAI and sends the changed files as well as your MindsDB credentials.

4. Renders the commenting template with the results that RevAI has provided.

5. Finally, comments out the review.

You can also set (a) default reaction(s) to RevAI's comments.

      - name: Create comment
        ...
        with:
          ...
          reactions: |
            heart
            hooray
            laugh

Tech Stack

• PyAction: Creating GitHub Actions in Python. (more..)

• MindsDB: AI Development Cloud Platform (more..)

Useful Links

• RevAI on GitHub: https://github.com/lnxpy/revai

• RevAI on Marketplace: https://github.com/marketplace/actions/aireviews

Conclusion

With the massive growth of AI and LLMs, we'll be seeing a huge improvement in our CI and even CD cycles. There will be no need for us (humans) to review or point out any approval for minimal changes. We have AI!

Special thanks to Hashnode and MindsDB for sorting up this cool hackathon. 🍻

In this article, we'll be using this handler to make a prediction over the future download rate of a Python package. Keep in mind that this method uses time-series training strategies and the output is from a linear regression model meaning the output is not quite accurate.

To make this process faster, I'm going to start up a local MindsDB instance and train my model locally. At the end of this tutorial, you'll have access to the Notebook files.

In this tutorial, we need..

• A local instance of MindsDB

• Jupiter Notebook (optional)

Setting Up

As I said, we need a local MindsDB instance. You can either run up a Docker container or do it in a traditional way using a venv and install the requirements inside the environment.

Follow this official tutorial to run a local MindsDB instance.

Make sure your MindsDB engine is up and running and navigate to http://localhost:47334/. You should see the dashboard.

Train Your Model

Now, we have to train a model before we jump into any further steps. To do so, you have to execute the following SQL code.

CREATE DATABASE pypi_datasource
WITH ENGINE = 'pypi';

CREATE MODEL mindsdb.pypi_model
FROM pypi_datasource
  (SELECT *
FROM pypi_datasource.overall WHERE package="<PACKAGE-NAME>" AND mirrors=true limit 500)
PREDICT downloads;

It creates a PyPI table and prepares a model based on the following SQL sequence.

SELECT *
FROM pypi_datasource.overall WHERE package="<PACKAGE-NAME>" AND mirrors=true limit 500)
PREDICT downloads;

You can refer to this document for more options and parameters if you need to modify your sequence.

I'm trying to predict the download rate of the requests library. It's a famous one so let's see how is our model going to do.

As you can see, my model's status is "generating" meaning my model is not yet ready. Once it's fully prepared and ready to be prompted, you'll see a check mark on the bottom-left part of your dashboard that says your "pypi_model" is ready to be used.

Predict

To do the prediction, I need a bunch of fancy tools to make an epic scene from my prediction. For that manner, I'm using Plotly which is a plotting library in Python. You can use any other tool that you need. To connect to the local MindsDB, I'm using mindsdb_sdk.

Before I jump into the connection phase, I need to set some variables.

# variables
DAYS_TO_BE_PREDICTED = 100
MINDSDB_INSTANCE = "http://127.0.0.1:47334"
PACKAGE_NAME = "requests"

Make sure to modify DAYS_TO_BE_PREDICTED and PACKAGE_NAME variables based on your needs.

from datetime import datetime, timedelta

import mindsdb_sdk

# variables
# ...

server = mindsdb_sdk.connect()
server = mindsdb_sdk.connect(MINDSDB_INSTANCE)

databases = server.list_databases()
database = databases[-1]

Let's take a batch from the download rate data to sort our model for prediction.

query = database.query(
    f'SELECT date, downloads FROM pypi_datasource.overall WHERE package="{PACKAGE_NAME}" AND mirrors=true limit 500'
)
overall_df = query.fetch()

Now, let's take our prediction data based on overall_df.

# an empty dataframe
predicted_df = pd.DataFrame(columns=["date", "downloads"])

today = datetime.today()
current_date = (today - timedelta(days=180)).date()

for i in range(DAYS_TO_BE_PREDICTED):
    query = database.query(
        f'SELECT date, downloads FROM mindsdb.pypi_model WHERE date="{current_date}"'
    )
    predicted_value = query.fetch()
    current_date = (today + timedelta(days=i)).date()
    predicted_df = pd.concat([predicted_df, query.fetch()], ignore_index=True)

Right after the for-loop, our predicted_df is filled with the predicted download rates on each day. This is a quick showcase on how this variable looks like.

As I said, I'll use Plotly to make a plot view from this data and the real values.

import pandas as pd
import plotly.graph_objects as go

# ...

fig = go.Figure()

fig.add_trace(
    go.Scatter(
        x=overall_df["date"], y=overall_df["downloads"], mode="lines", name="Data"
    )
)
fig.add_trace(
    go.Scatter(
        x=predicted_df["date"],
        y=predicted_df["downloads"],
        mode="lines",
        name="Prediction",
    )
)
fig.update_layout(
    title="PyPI Package Download Rate Prediction",
    xaxis_title="Dates",
    yaxis_title="Downloads",
    template="plotly_dark",
)

fig.show()

Hope you've found this implementation helpful.

Useful Links

• PyPI Handler: https://github.com/mindsdb/mindsdb/tree/staging/mindsdb/integrations/handlers/pypi_handler/

• PyPI Prediction Notebook: https://github.com/lnxpy/pypi-prediction-examples/

TL;DR

MindsDB is a cloud database service with a lot of AI and data integrations that help you design, train, and predict over the cloud!

MindsDB's community has always been welcoming all contributions over their repositories. Since they have such nice support for their products alongside their active community, I decided to write down this quick tutorial on how you can contribute to MindsDB by creating your handler integrations.

This guide is created for those who want to contribute to mindsdb/mindsdb so without further ado, let's talk about the steps.

Fork & Clone

First thing first, make sure that you have mindsdb/mindsdb forked and cloned on your machine. Change your directory to where the codebase is on.

Create A Handler

I've written a tool that helps you create MindsDB handlers with a few question answerings. It's basically a Cookiecutter template that provides whatever you may need during your handler development. Follow the steps to create a basic handler template for yourself.

1. Install Cookiecutter

Make sure you have Python and pip installed and updated on your machine and install the cookiecutter package via the following command.

pip install -U cookiecutter

To test it out and find out whether the installation was successful, run it with the -V flag.

cookiecutter -V

2. Generate the template

Now, it's time to use my tool called lnxpy/cookiecutter-mindsdb to generate a simple handler for yourself. MindsDB stores all the handlers in mindsdb/integrations/handlers/ so we need to put our handler in that path too. Keep in mind that we've already changed our directory to mindsdb/.

cookiecutter gh:lnxpy/cookiecutter-mindsdb -o mindsdb/integrations/handlers/

After running the above command, it tries to retrieve the content of the cookiecutter template and then, it asks you a bunch of questions in order to create the most suitable handler for you. The following table helps you answer the questions accurately.

When you see the following message, it means that your handler has been created successfully in that specific handler's path of MindsDB.

+ Sample Handler is created successfully!

If you navigate to the path to your handler, a quick tree view of your handler would be like the following scheme.

<name>_handler/
├── README.md
├── __about__.py
├── __init__.py
├── <name>_handler.py
├── <name>_tables.py
└── icon.svg

1 directory, 6 files

The files that need to be updated are README.md, <name>_handler.py, <name>_tables.py, and icon.svg. If your handler has any dependencies, once you've installed the dependencies, don't forget to update the requirements.txt file and put the output of pip freeze command into it as follows.

pip freeze > requirements.txt

In the next two sections, we'll be talking about each file and method so that you can write your handlers in a flash!

Develop Your Handler

In this section, we'll be going through both _handler.py and _tables.py files and their instructions. To run a local instance of MindsDB, create a virtual environment, install the dependencies, and run it with the following commands.

$ virtualenv venv && source venv/bin/activate
$ pip install -e .
$ pip install -e ".[dev]"

The following command runs the MindsDB engine on your local machine and shows the exact port that it's accessible from.

$ python -m mindsdb

Let's dive into the <name>_handler.py and <name>_tables.py files that contain most of our implementations. In my case, my handler name is Sample so I'll bring examples and practices based on this name.

Handler Development

The following handler stub structure is generated in sample_handler.py by default.

class SampleHandler(APIHandler):
    def __init__(self, name: str, **kwargs) -> None: ...
    def check_connection(self) -> StatusResponse: ...
    def connect(self): ...
    def native_query(self, query: str) -> StatusResponse: ...

We'll go through each method and the way you should implement them.

SampleHandler.__init__() Method

The SampleHandler.__init__() method gets triggered on the following CREATE DATABASE query execution over in the dashboard.

CREATE DATABASE sample_db
WITH ENGINE = 'sample';

Inside this method, you should create the tables that you need. As you can see, there is already a SampleTable class created there by default. Create your required tables inside <name>_tables.py, import them into the <name>_handler.py and add them in _tables variables inside the __init__() method.

...
from mindsdb.integrations.handlers.sample_handler.sample_tables import SampleTable


class SampleHandler(APIHandler):
    def __init__(self, name: str, **kwargs) -> None:
        """initializer method

        Args:
            name (str): handler name
        """
        super().__init__(name)

        self.connection = None
        self.is_connected = False

        _tables = [
            SampleTable,
            #...
        ]

        for Table in _tables:
            self._register_table(Table.name, Table(self))

Notice that there are two attributes called self.connection and self.is_connected inside the initializer method. We need to set them from within the connect() and check_connection() methods.

SampleHandler.check_connection() Method

This method has to return a StatusResponse(True/False) object meaning the handler is still available to access the third-party for the further communications. This method is also where we set a bool value for self.is_connected. A quick sample for this method would be like this.

    ...
    def check_connection(self) -> StatusResponse:
            response = StatusResponse(False)

            try:
                _ = requests.get("https://google.com", timeout=5).raise_for_status()
                response.success = True
                self.is_connected = True
            except requests.exceptions.RequestException as e:
                response.error_message = e

            return response

SampleHandler.connect() Method

This method is where you have to put a value into the self.connection attribute. A good example for this would be returning a requests.get() object.

    ...
    def connect(self) -> Callable[..., Response]:
        """making the connectino object

        Returns:
            Callable: requests.get
        """
        self.connection = requests.get
        return self.connection

We need the value that this method puts into the self.connection later in our sample_tables.py.

Tables Development

Now, let's see the sample_tables.py and the methods and classes that live there. You can copy and paste your tables from the initial SampleTable or even modify it. The first step is to specify each table's columns and names. You can do this by changing the name and columns attributes of each class.

class SampleTable(APITable):
    name: str = "sample"
    columns: List[str] = ...

    def __init__(self, handler: APIHandler): ...
    def select(self, query: ast.Select) -> pd.DataFrame: ...
    def get_columns(self, ignore: List[str] = []) -> List[str]: ...

There is a SampleTable.select() method defined by default. This is the only method that you probably need to change. This method is called whenever someone queries a SELECT statement over your table. All the parameters and clauses that the user specifies can be reachable from the query attribute.

You can define other methods such as SampleTable.insert() for the INSERT INTO purpose.

Don't Forget to..

I highly recommend you take a look over other the handler integrations' source code. They'll give you a nice point of view about the components and how they're supposed to be implemented. As references, I suggest the MediaWiki Handler and PyPI Handler which I maintain!

What's more, Artem Veremey has published "Building a New MindsDB Integration: A Step-by-Step Guide With Examples From the GitHub Handler" article over on his blog that might give you more perspectives and ideas about this integration. Shout out to him!

Conclusion

In this quick tutorial, we talked about MindsDB and the way you can ship your desired handlers over it via a simple Cookiecutter template. Hopefully, this tutorial has helped you build your integrations easier.

Nested F-Strings

In Python 3.12, you can have nested f-string phrases. Check the following example.

phrase = f"Hello {f"{name}"}"
# Hello Sadra

IMO: It seems to be quite hard in term of understanding a nested f-string phrase as it might not be as practical as the simple f-strings. I would personally regret using this new feature.

Multiline F-Strings

One cool feature that's been brought to the new 3.12 version is that you can have multiline f-strings.

phrase = f"Hello {
    name # User.name
}"
# Hello Sadra

IMO: This is a handy one. As you can see, you can expand your f-strings as well as document them via comments. That's amazing!

Tokenization is Re-written in C

Since Python 3.11, the tokenizer module has been in Python analyzing your Python lexical and keywords. From now on, due to the new nested and multiline f-strings, this module has been updated and re-written in C and it's almost 40% faster than before. With this huge improvement, all the linting and formatting tools that make use of this module can get a huge performance improvement over this update.

IMO: Now I can run my CI worklfows way faster!!

Distutils is Depricated

There's always been a struggle among the Python community members about setuptools against distutils and the reason that everyone prefers the setuptools (which is a fork of distutils) over the official distutils. That's actually because setuptools is better with lots of more features and functionalities. That's why they decided to remove the distutils standard library and depreciate that.

What's more, pip actually uses setuptools for building the distributions. If you make a venv with python<=3.11 and pip<=22.1 you'll see that the setuptools is already installed there.

$ pip list
Package    Version
---------- -------
pip        23.2.1
setuptools 68.0.0    <--
wheel      0.41.1

The setuptools package is not a standard library. It just uses distutils. Since distutils is no more available and pip>=22.1 is not dependent on setuptools, we'll never have a distributing tool inside a freshly installed Python environment.

The setuptools package has dropped its dependency on the virtualenv package as well. It means even if you install the setuptools, you won't be able to create a virtual environment or even run the following command.

$ python -m venv venv
# ERROR: venv module is not found.

The distutils package has become another whole third-party package. In order to have access to both virtualenv and setuptools, you have to install them separately.

IMO: This deprication has made lots of changes. You won't have acces to any distributing tool anymore. No more distutils, setuptools or virtualenv by default. In fact, this quick change ensures you from a real isolated venv and that's a positive point. From now on, if you make a virtual environment, nothing is installed there except pip.

**kwargs Type Hinting

In the new update, lots of changes have happened to the typing module. I used to use typing.Any for type hinting the **kwargs of my functions and method. That was actually quite a deal but in Python 3.12, you can give it a more precise type annotation using typing.TypedDict.

from typing import TypedDict, Unpack

class Values(TypedDict):
    name: str
    age: int

def main(**kwargs: Unpack[Values]): ...

IMO: I'd prefer to keep kwargs un-annotated for now.

@override Type Hinting

There's a new @override type-annotation included in the typing module. It actually helps you to specify the methods that are meant to be overridden in the OOP design. Using this feature helps the typing tools such as mypy debugging your code in another sense.

from typing import override

class A:
    def greet(): ...

class B(A):
    @override
    def greet(): ...

For instance, in the above example, if you make a typo issue and change B.greet to B.great, your mypy would most likely return a non-zero output in the STDOUT meaning the method that's meant to be overridden is not defined in the base class.

IMO: I find this little trick quite useful actually. Also including a mypy execution in your CI pipelines would help you catch such issues.

New type Defining

There has been a new syntax added to the new Python version. This new convention helps you define the `Type Aliases` easier.

• Before:

    from typing import TypeAlias
  
    Students: TypeAlias = list[str]
  
    def list_students(students: Students) -> None: ...
  

• After:

    type Students = list[str]
  
    def list_students(students: Students) -> None: ...
  

This new convention has changed how functions and methods look in Python as you can design your function scopes as follows.

• Before:

    def list_students(students: List[str], grades: List[float]) -> None: ...
  

• After:

    type Students = List[str]
    type Grades = List[float]
  
    def greet[Students, Grades](students: Students, grades: Grades) -> None: ...
  

The new pattern of the function definition is like def NAME[*TYPES](*ARGS: TYPE) -> TYPE. Keep in mind that the types that are included in front of the name of the function are limited to the function scope.

IMO: I think this feature just violates the readability of the new function. I'd prefer them in the old way if declaration. Highlighting tools might change my mind though. We have see how they're going to deal with these new syntaxes and keywords.

Per-Interpreter GIL

In the new update, we'll have full control over the GIL utilization in the sub-interpreters that we make. As the official docs say..

This (Per-Interpreter GIL) allows Python programs to take full advantage of multiple CPU cores.

We'll be talking about this new integration soon in another blog post. It seems to be a decent improvement over the performance manner.

Conclusion

In this blog post, we talked about the major features and updates that are about to happen in Python3.12 and the new syntaxes that help us code in a cleaner way. Lots of new features are coming from the Typing module meaning the lining and formatting tools have to work harder in the incoming months to release a compatible version with the new Python patch.

• Docker-based Actions

• Javascript Actions

• Composite Actions

As you can see, GitHub's runners officially support shell-based and Javascript-based actions. What if we need to implement the actions in Python?!

Of course, we can use either Docker-based or Composite types for creating our Python actions but is that the real deal?! What if we need to access the variables declared during the workflow run? Since Python is not officially recommended as a tool for writing actions, it doesn't mean we can't have actions in Python.

I wrote an open-source template called PyAction that allows you to write GitHub Actions in Python. You have almost all the accesses that a Javascript developer has but in fact, you're using Python's syntax and have Python's power.

In this article, we will make a quick hello-world demo action project using my tool. I hope this article helps you out in case you're using PyAction.

Introducing PyAction

PyAction is a Cookiecutter template that helps you write Actions in Python. It's based on the Dockerfile implementation that GitHub recommends and has some workflow-related features that allow you to have access to the variables and data transferring during your workflow executions that we'll see later on.

Note: This tutorial is based on PyAction v0.1.0

Creating Actions

In this section, we'll be implementing a hello-world action using PyAction from the very first step.

Install cookiecutter

The tool that you need to generate a PyAction template is nothing but cookiecutter. Make sure you have Python and pip installed and updated on your machine and install cookiecutter.

pip install -U cookiecutter

Once you have this package installed, make sure that it's installed successfully by checking its version number.

cookiecutter -V

Generate the hello-world template

Use the cookiecutter template to pull PyAction's template.

cookiecutter gh:lnxpy/cookiecutter-pyaction

At this point, Cookiecutter will ask you some questions to generate the most suited action for you. Here is how I managed to answer the questions for my hello-world action. I only listed the important answers.

If you want to release your actions in the GitHub Marketplace, make sure you choose a unique action name as GitHub warns..

• The name in the action's metadata file must be unique.

  • The name cannot match an existing action name published on GitHub Marketplace.

  • The name cannot match a user or organization on GitHub, unless the user or organization owner is publishing the action. For example, only the GitHub organization can publish an action named github.

  • The name cannot match an existing GitHub Marketplace category.

  • GitHub reserves the names of GitHub features.

Adding dependencies for your action: If your action has dependencies, make sure to put y for the Include dependencies prompt. All it does is it creates a requirements.txt file as well as an additional layer in your Dockerfile. Install the requirements of your

Once you answered all the questions, your action will be in hello-world/. Here is a quick tree of what we have so far.

hello-world
  ├── Dockerfile
  ├── LICENSE
  ├── README.md
  ├── action.yml
  ├── actions
  │     ├── __init__.py
  │     └── io.py
  └── main.py

All we need to change are action.yml, main.py, and README.md files.

Implementation

We want the users to be able to pass a name variable to our workflow and see a Hello {name} message in their workflow running logs tab. So, our action has only one INPUT and OUTPUT. Here is how we should change the inputs and outputs values of the action.yml file.

...
# == inputs and outputs ==

inputs:
  name:
    required: false
    description: the person/thing you want to greet
    default: World

outputs:
  phrase:
    description: output message

This way, the users can call our action with their desired name value. After that, they will have access to the phrase variable which contains the greeting message.

Now, it's time to write a simple hello world program in our main.py file.

import os
import sys
from typing import List

from actions import io


def main(args: List[str]) -> None:
    """main function

    Args:
        args: STDIN arguments
    """

    # reading the name variable from `with`
    name = os.environ["INPUT_NAME"]

    # writing to the buffer
    io.write_to_output({"phrase": f"Hello {name}"})

    # now, people can echo `phrase`


if __name__ == "__main__":
    main(sys.argv)

Testing

Let's push our action to GitHub and test it in a simple workflow. I'm going to create a workflow inside my action repository to test it. You can test your action from whole another repository.

For that matter, I create a simple workflow before I push it to the GitHub repository that I've created before. Here is my main.yml workflow.

# .github/workflows/main.yml
name: Testing My hello-world Action

on: workflow_dispatch

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - id: greetings
        name: Using hello-world
        # use the action that's inside the same repository
        uses: ./
        with:
          name: Sadra

      - name: Echo phrase
        run: |
          echo ${{ steps.greetings.outputs.phrase }}

We're almost set. If you head over to the Actions tab, you'll see that your workflow is listed there. Since it gets triggered on the workflow_dispatch event, you can run it manually.

Run the workflow and go to the workflow running tab to see the steps passing. Let's see if our hello-world action is working correctly. It's supposed to echo out the phrase variable with name=Sadra.

As you can see, inside the "Echo phase" step, it can access the name variable. That's amazing.

This time, remove the with statement inside your main.yml workflow to check if the default World value that we set for INPUT_NAME works. Here would be the newly updated main.yml file.

      ...
      - id: greetings
        name: Using hello-world
        # use the action that's inside the same repository
        uses: ./
        # no more with

      - name: Echo phrase
        run: |
          echo ${{ steps.greetings.outputs.phrase }}

Head back to the Actions tab and run the workflow once again. This time, we suppose our action to put Hello World inside the phrase environment variable.

And that's it. With a little bit of changing the main.py and action.yml files, you can create awesome handy actions. You can even tag your actions and publish them on the GitHub Marketplace. Check the next section for more instructions on that.

Useful Links

Here is the PyAction repository on GitHub. Don't forget drop by and show us your love by giving the project a little shiny star. :)

• PyAction on GitHub

The example that I brought you here today is available on my GitHub repository as well. You can check it for the sake of more clarity.

• Hello World project using PyAction on GitHub

If you want to choose branding icons and colors, you may find this tiny tool useful. It helps you find a proper branding icon as well as a color for your action. (branding is only available for marketplace actions)

• GitHub actions branding cheat sheet

DO NOT forget to follow the official instructions if you've aimed to publish your action on the marketplace. Here are the docs.

• Publishing actions in GitHub Marketplace

• GitHub actions branding

Conclusion

This article gives you a brief showcase of how you can write GitHub Actions in Python using PyAction. Throughout this quick tutorial, we created a hello-world action via PyAction and pushed it to GitHub, and saw how our Python source code work underneath our workflows as actions.

In the last six months, I participated in two hackathons and won 3000$ in total for two different submissions (projects).

PasteMe - Paste Codes From Your Terminal

Hey - Your AI-powered Pair Programming Friend

Put Effort

In both the projects that I submitted for the competitions, I tried my best in terms of development, maintenance, and presentation. If you keep all these three terms in mind, you will nail it.

• Development

• Maintenance

• Presentation

Development

Thinking of development as the phases you pass to finish up your project. Make sure you use the right conventions, best practices, system design, and architecture for your software product. Once you got your codes working, attempt to refactor them.

Maintenance

This term is somehow related to development. If you've had a healthy development and shipment process, you'd likely be good to go for maintenance. Writing programs is easy but making them maintainable is completely a different process. Always leave room for further developments.

Presentation

This is probably the most important term in the case of a hackathon. When it comes to presentation, always think of a way you could showcase your project clearly and precisely. If you're working on a short intro video, make sure to present the whole point of your project. Showcase the problem first, then your project as the rescue!
Being straight to the point would help your project to get viral and well-known. There are different things you could do in this phase.

• Write an easy-to-understand article and README for your project.

• Choose a theme for your project if possible.

• Make a motion graphic about your project.

• Make a short introduction video working with your project.

As you can see, I used to obtain a galaxy-like theme for PasteMe. All Octocat images on the website are wearing spacesuits. Its logo itself reminds me of Alian's spaceships and whenever I open the website, I feel like I'm not on Earth anymore but in another dimension.

Story-telling

Always make use of fiction in your presentation. It makes the audience more curious about the next thing you're going to talk about. As an example, I wrote the following sub-title in PasteMe.

Legends believe that this project is developed from space..!! Let's see..
~PasteMe

Once a person sees such a title, he/she becomes a little curious about the article. "It must be something to do with space and galaxy or stuff through this project.." he/she thinks. Once they open your article, it's time to get their attention via making an Agreement meaning you talk about shared struggles, concerns, and problems they've felt through their lives. Let them know that you've been hurt by those problems as well but enough is enough. Your introduction sections should start sad and painful but end epically and proudly just like there's something about to happen in the next sections. Something game-changer.

Product Thinking

Think of something useful. Something that literally solves a concern. I personally, try making something handy for myself. It had been a few months since I'd been struggling with showing my code snippets to my friends but in a better fancy way. That was the starting point of PasteMe. In case I made Hey, I needed some sort of an in-line ChatGPT prompt when I'm working through CLIs and command-line shells. I needed them, so I made them in my way.

Take Feedback

Having a network means standing in the frontline with hundreds of people supporting your work. You can always rely on them and ask them for their valuable feedback on your projects, ideas, and movements. Always present your work to them. If you're working on a project as a submission for a hackathon, let them know your progress and ask them for improvements, feature requests, and reviews first. Almost tens of features and modifications I made over on my projects were due to the feedback I received from my connections on LinkedIn so value them and think of having a network with people with similar interests and career experiences.

Conclusion

In conclusion, always make sure to work on something that's worthy. Blast on the stage with the presentation you've got about your project. Showcase all aspects of your idea as we went through all its steps during this article.