Forem: Edun Rilwan

A Goldmine for documentation leads/Technical writers

Edun Rilwan — Thu, 15 May 2025 15:34:29 +0000

Edun Rilwan

May 13 '25

How to Migrate Technical Documentation: Tools, Checklist, and Tips

#documentation #git #writing #ssgs

Comments

8 min read

How to Migrate Technical Documentation: Tools, Checklist, and Tips

Edun Rilwan — Tue, 13 May 2025 20:38:57 +0000

Your documentation platform might be the reason behind your growing user frustration and your team's productivity slump and you probably don’t realize it.

Documentation platforms are SaaS tools that help businesses create and publish documentation for their technical products. They simplify the process by offering boilerplate solutions like templates, themes, and ready-made components, making it easy to launch a fully functional documentation site quickly.

These platforms range from no-code solutions like Document360 and KnowledgeOwl, to low-code or code-first tools such as Docusaurus, GitBook, Astro Starlight, and Mintlify.

In this article, we’ll focus on the low-code/code-first category which are often referred to as Static Site Generators (SSGs).

SSGs are widely used for developer-facing documentation. Their primary function is to generate static HTML pages from source files like Markdown. However, they’ve gained popularity among technical writers because they integrate smoothly with developer tools and workflows making them ideal for documenting technical products.

Most SSGs come with well-structured project templates and support features like Markdown editing, version control, customization, automation, collaboration, and reusable components/utilities.

If your current documentation platform lacks many (or most) of these capabilities, it might be time to consider migrating your documentation.

What is documentation migration

Documentation migration is the process of moving your documentation and its content from one platform to another. There are several reasons why teams choose to migrate their documentation. These reasons can be personal, technical, structural, or financial.

Documentation migration is especially common in growing startups. Early on, when the team is small and requirements are minimal, technical writers may not have a well-defined reason for choosing a particular documentation tool. They often go with whatever works at the time, focusing on speed and quick deployment.

But as the product evolves and documentation needs become more complex, the limitations of the initial platform become harder to ignore. Eventually, migrating to a more flexible and capable platform becomes necessary.

When to consider migrating your documentation

Easy collaboration, simplicity, automation, and continuous integration are essential features to look for when choosing a documentation tool/platform. These capabilities help streamline the documentation process and boost your team’s productivity.

Once you’ve confirmed that the platform's tech stack aligns with your team’s skills and tools, the features mentioned above should be part of your evaluation checklist.

Not sure if it’s time to migrate your documentation? The following signs can help you decide whether switching to a new platform is the right move.

A. Technical difficulties:

Some documentation platforms or SSGs can be challenging to set up, use, or deploy. They might have a unique setup process or offer limited support for certain operating systems, which can hinder collaboration. If technical writers (including external contributors) struggle to test the documentation locally on their machines or if your team frequently encounters bugs and errors, it may be time to consider a more accessible and developer-friendly platform.

B. Skill gap:

The choice of documentation platform should align with your team’s skillset. For example, if your technical writers have limited experience with JavaScript, platforms like Mintlify, GitBook, or MkDocs may be a better fit. On the other hand, if your team is proficient in JavaScript or React, tools like Docusaurus might offer more flexibility and control.

That said, there’s a trade-off to consider. If the more suitable platform lacks essential features compared to your current tool, your team may need to invest time in upskilling rather than switching to a less capable alternative.

C. Financial constraints:

Not all documentation tools are free. Platforms like Mintlify require a paid subscription to access premium features. If your current platform is becoming too expensive, it might be worth exploring more budget-friendly or open-source alternatives without sacrificing key capabilities.

D. Limited collaboration:

A good documentation platform should support effective collaboration, especially for distributed teams. Features like version control help track changes, identify contributors, and roll back errors when needed. If your current tool lacks collaboration features such as Git integration or commenting, it may be limiting your team’s workflow and accountability.

E. User Experience and customization:

User Experience refers to the overall user satisfaction while reading your documentation. A good documentation platform should have a good user experience that ensures your audience are satisfied when using your documentation.

A platform with poor UX can frustrate users and affect their ability to find the information they need. Look for platforms that support: responsive design across devices, clear and readable typography, light/dark mode, Alt text for accessibility, customization options for branding,such as fonts, colors, and layout.

For example, Docusaurus allows customization using React and CSS/TailwindCSS making it easier to align the documentation with your brand identity.

F. Scaling challenges:

As your product or company grows, your documentation might outgrow its current structure or platform, requiring a more scalable documentation platform.

G. Security or compliance requirements:

Regulations or internal policies may necessitate a move to a platform that offers better access control, encryption and on-premise deployment.

H. Integration and automation:

Your docs should be easily integrated with CI/CD pipelines or analytic tools to track everything that's going on with your docs. If your current documentation platform doesn't support it, it's a sign to migrate.

Steps to follow when performing a documentation migration

1.Identify and select a documentation platform:
The first step is to choose a documentation platform that aligns with your team’s technical skill level, your company’s budget, and the size or complexity of your project.

Each of these factors should be carefully considered before making a decision. This step is critical to ensuring the long-term success of the documentation and avoiding future migrations.

2.Create an action plan:
An action plan outlines the path your migration will take. It serves as a roadmap defining objectives, tasks, and deliverables, helping the team stay organized and focused.

Some of the items to include in your action plan are the project deadline, number of contributors, and documentation sections. For example, if you're migrating documentation for a developer tool, the action plan should break it down into logical parts like “Getting Started,” “Advanced Concepts,” and “Troubleshooting.” Each section should have a clear timeline for completion.

3.Apply the divide and conquer strategy:
The documentation lead should divide the team into smaller groups, each responsible for a specific section of the documentation. If the team is small (1–3 people), then assign each person a section based on workload and expertise. This approach helps break the project into manageable stages and ensures progress is steady and organized.

4.Check-in frequently on the project's progress:
It’s important for the documentation lead to regularly check in on the migration process. Encourage each sub-group (or individual, if applicable) to report on their progress and raise any blockers they encounter.
This ensures the team stays aligned, and problems can be addressed promptly before they escalate.

Tips for migration

A. Migrate first, finetune later:

Don't get stuck trying to perfect every detail before completing the migration. Move the bulk of your content to the new platform first, then refine structure, formatting, links, and SEO gradually. This helps maintain momentum and avoids unnecessary delays.

B. Understand git perfectly:

Most low-code documentation platforms rely on Git for version control and collaboration. Ensure that everyone involved in the migration has a good grasp of Git basics like branching, committing, merging, and resolving conflicts. This prevents errors and saves hours of rework during migration.

C. Outsource for contributors:

If your internal team is too small or overwhelmed, consider bringing in external contributors like technical writers, open source contributors, or freelancers who are familiar with the platform you’re migrating to. This boosts speed, brings fresh perspectives, and distributes workload more efficiently. Most technical writers are always willing to contribute for free in exchange for experience.

D. Clearly outline the migration goals:

Before migrating, define the objective of the migration. Are you migrating to improve SEO, enhance user experience, simplify collaboration, or reduce costs? When goals are clear, your team stays focused and aligned throughout the migration process.

E. Create a clear communication channel:

Set up a centralized and clear communication channel like Slack, Discord, Notion, or whatever works for your team—to track progress, raise issues, and provide updates. Effective communication reduces misunderstandings and helps the team handle issues quickly.

F. Inform your users:

Let your documentation users know that a migration is underway (or has happened). Provide a brief announcement or changelog, especially if URLs, navigation, or layout have changed. This builds trust and ensures users aren’t caught off guard when things look or behave differently.

Conclusion

Migration can be very demanding, especially when large documentation is involved. However, the process can be made easier by splitting the entire process into smaller chunks, assigning each chunk to teams/writers, and setting realistic milestones. Finally, everyone must be committed to the project's success and there should be consistent communication between everyone involved.

Docs-as-code in action: Documenting a Python library.

Edun Rilwan — Wed, 22 Jan 2025 10:36:38 +0000

Documentation is a crucial resource for helping your target audience understand how to use your product effectively. High-quality documentation not only communicates the core problem your product solves but also empowers users to achieve their desired outcomes seamlessly.

The same holds true for open-source libraries and packages. Clear and accessible documentation is essential for guiding developers on how to integrate these tools into their projects successfully.

In recent years, the Docs-as-Code (DaC) approach to documentation has gained significant popularity. This method treats documentation as a fundamental part of the software development lifecycle by using the same tools and processes developers rely on for code.

This method is widely accepted because it promotes consistent, version-controlled, and easily maintainable documentation that evolves alongside the product.

What is Docs-as-code?

In simple terms, DaC is a method that involves handling and maintaining documentation as you would do to your code.

A typical software development life cycle involves 7 stages which include the following:

Planning
Gathering Requirements and Analysis
Design
Coding and implementation
Code testing
Code deployment
Code maintenance

Therefore, DaC is a new approach that ensures documentation goes through the same stages. This keeps the documentation versioned and up to date with software changes.

Deployment without DaC

Deployment with DaC

While this guide may not go in-depth into the theoretical aspect of DaC, you can explore the Beginner’s guide to Docs-as-code article which explains the concept behind DaC in detail.

Project Overview

This guide involves the practical implementation of DaC with Python. You will learn how to document an open-source Python library using Mintlify.

Mintlify is a static site generator and documentation site used for public-facing documentation. It is easy to maintain and use for various documentation needs such as developer documentation, API documentation, etc. It also works well with the DaC methodology.

This tutorial is a sequel to an existing tutorial on how to build and deploy a Python library. Using the DaC methodology, you'll learn how to document the Python library developed referenced tutorial.

It is recommended that you complete the previous tutorial before you continue. However, you can proceed if you have an existing project to use for this tutorial.

Project requirements

A basic knowledge of Git and GitHub, how to create a Github repository and how to push your code to GitHub us required. You also need the following tools for this tutorial:

Mintlify account: You need an active Mintlify account to create documentation (steps will be provided in the guide).
Node.js: You will need Node.js version 18 and above to install Mintlify and edit your documentation locally.

Setup a Mintlify documentation

Follow the steps below to setup a documentation using Mintlify:

1. Create an account on Mintlify

2. Setup your Mintlify account:
A verification link will be sent to your mail. This link will redirect you to the page below:

3. Sign in with Github:
The first step requires you to sign in with your Github account.

4. Create a GitHub repository (repo) for your documentation:
The next step requires you to install and authorize the Mintlify app on your Github account. This allows Mintlify to automatically create a repo for your docs

5. Access your documentation repo:
The previous step creates a new docs repo for your documentation. Check your GitHub repositories for a new docs repo

Add the documentation to your project

The next step is to clone the docs repo to your local environment and add it to an existing project such as a developer tool, open-source package, etc. If you already completed the previous tutorial, your project will be exchangeLibrary.

Follow the steps below to add the documentation to your project:

1. Open the terminal and clone the docs repository with the command below:

git clone https://github.com/<your github username>/docs

2. Copy the cloned docs folder to your project.

3. Open the project in a code editor.

Your project file structure should now look like this:

Preview documentation locally

Mintlify allows you to preview your documentation locally before publishing it. Follow the steps below to set it up:
1. Open your project in the terminal
2. Run the command below to install Mintlify globally:

npm i -g mintlify

3. Switch to the docs folder in your project:

cd docs

4. Start a mintlify server with the command below:

mintlify dev

You should see a message like the one below in your terminal:

Open the URL to preview the documentation locally. The content of your documentation will be the Mintlify starter doc template. This will change when you start editing your documentation.

Writing the documentation

A Mintlify documentation is powered by the mint.json file. This file contains the color scheme, pagination, and navigation settings for the documentation. You can find it in the project’s docs folder.

Also, documentation files in Mintlify are written in .mdx. It is almost similar to markdown(.md) except that it allows special tags and symbols.

In this section, you will learn how to edit your documentation settings in the mint.json file, and how to add texts and special components to your documentation.

Edit documentation settings

The mint.json file is a JSON object made up of color schemes, pagination, navigation settings, etc. for your documentation. Below is a list of available settings and what they mean:

1. Color scheme and appearance:
This section is used to beautify and enhance your documentation appearance. It is used to change the logo (for both light and dark mode), favicon, title, and color scheme for the documentation. It starts from the $schema key to the colors key as seen below:

  "$schema": "https://mintlify.com/schema.json",
  "name": "<your-documentation-title>",
  "logo": {
    "dark": "<logo-for-dark-mode>",
    "light": "<logo-for-light-mode>"
  },
  "favicon": "<link-to-a-favicon>",
  "colors": {
    "primary": "#0D9373",
    "light": "#07C983",
    "dark": "#0D9373",
    "anchors": {
      "from": "#0D9373",
      "to": "#07C983"
    }
  },

2. Navigation links and CTA button:
This section is used for setting up navigation links and buttons at the top of the documentation page. Below is an example of a navigation link and button:

The code below sets up the navigation links and a CTA button for your Mintlify documentation:

  "topbarLinks": [
    {
      "name": "Community",
      "url": "https://mywebsite.com/community"
    },
    {
      "name": "Log In",
      "url": "https://mywebsite.com/login"
    },
  ],
  "topbarCtaButton": {
    "name": "Get Started",
    "url": "https://mywebsite.com/get-started"
  },

3. Tabs and anchors:
Tabs and anchors can be used to set up horizontal and vertical sections respectively in your documentation. Below are examples of tabs:

Below is an example of an anchor:

The settings for these components are handled by the tabs and anchors keys.

4. Navigation settings:
This section helps you to group the pages in your documentation. It is an array consisting of a group key, and a pages array where the pages for the group are added sequentially. Below is an example of how it is added:

“navigation”: [
{
  "group": "Get Started",
  "pages": [
    "introduction",
    "installation",
    "authentication"
  ]
}
],

The settings above will translate to the image below:

The pages(introduction, etc.) are .mdx files in your project’s docs folder.

5. Nested navigation:
Nested navigation is commonly used to create subsections within a documentation. Below is an example of a nested navigation:

Below is a sample code to set up a nested navigation on Mintlify:

"group": "APIs",
   "pages": [
     {
       "group": "Exchange API",
          "pages": [
            "<a-path-to-a-mdx-file>",
            "<a-path-to-a-mdx-file>",
            "<a-path-to-a-mdx-file>",
            "<a-path-to-a-mdx-file>"
          ],
          "icon": "money-bills"
     }
],

The code above nests a section/group within another section. The icon key beautifies the section title with an icon when rendered on a web page.

6. Footer settings:
The footerSocials key is used to add social media accounts related to the documentation. Below is an example:

How to add content

The Mintlify documentation guides you on how to add content to your documentation. I recommend you check out the documentation to learn how to add different content to your documentation.

Check out this sample documentation for inspiration on how to structure your own documentation.

Documentation writing tips

Below are few tips to help you write clear and user-friendly documentation:

Be as direct as possible: Avoid extraneous information that adds no value. Your documentation is for developers who want to use your package or tool in their next project so only show them what they need to achieve this.

2. Add a description or overview of your tool:
Before going into details on how to use your tool, briefly describe what your tool is and the problem it solves. This should be on the first page.

3. Add enough code samples:
This will help them understand how to use your tool without unnecessary errors. Code samples on installation, authentication, response samples, method arguments, etc are very important.

4. Errors and exceptions:
This will help users in debugging. Add a page to describe the kind of errors users may encounter when using your tool. Also show code samples for this.

Push the project to Github

Follow the steps below to push the project to Github:

1. Open a git bash terminal in your project and switch into the docs folder with the command below:

cd docs

2. Remove git from this folder with the command below:

rm -rf .git

This command removes .git from the docs folder to avoid issues when you want to push the entire project to Github.

3. Push the project to GitHub.

Deploy the documentation

Follow the steps below to deploy your documentation on Mintlify:
1. Login to your Mintlify dashboard
2. Click on the Settings tab

3. Change your Mintlify Github repo to your project’s repo

4. Activate the monorepo switch. This signifies that the docs folder exists within another project in a single repo.

5. Enter **docs as the path to the mint.json file in the new field that appears.**

6. Click the save button to save changes.

Your documentation can be accessed via the link displayed in the overview tab of your dashboard

Updating the Project

You’re most likely to make changes to your project and may need to redeploy it.

After making any updates in your project, ensure you push the changes to Github. Mintlify automatically picks up the new changes and updates your docs promptly.

Conclusion

In this tutorial, you learnt how to build documentation for a Python library using the docs-as-code approach.

Docs-as-code promotes collaboration and continuous integration on a project. When it comes to open source, docs-as-code allows people to collaborate seamlessly on a project while maintaining proper documentation that is up-to-date.

There are different REST APIs without SDKs or programming libraries. Select one that interests you and create something similar.

Keep building 👩‍💻!

FAQs

How can I test my documentation?

This feature is often used on large projects with multiple contributors. Documentation testing is run automatically when a pull request is made to the Project. If the test is successful, the changes are merged. Read this guide on how swimm offers automatic documentation testing to learn more.

Can I replicate this project in other programming languages?
Yes you can. Follow the procedures in this guide to get a similar result in your preferred language.

Are there other documentation sites except Mintlify?
Yes there are other documentation sites you can use. Some of them include: Gitbook, Readme, Docusaurus, etc.

How to build and deploy a Python library

Edun Rilwan — Tue, 21 Jan 2025 12:14:23 +0000

In software programming, there are lots of repetitive tasks which are popular in most projects. These tasks often require the same code and logic to be completed. This poses a huge problem for programmers as they always have to rewrite the same code and logic for each project. Examples of such tasks include validating an email, generating random strings, etc.

A popular solution to this problem is by packaging the code into an installable package (also known as a library). The package can then be installed and used in every project without having to rewrite the logic. In most cases, such packages are always open-sourced and available for the public to use for free.

This practice is common in most programming languages such as Python, JavaScript, etc. Through this tutorial, you will learn how to build and deploy a Python library to Pypi - the official repository for Python libraries.

Project Overview

This tutorial will guide you on how to build and deploy an open-source Python library that wraps a REST API and its endpoints.

The Python Library

The library you will build is a wrapper for the Exchange Rates REST API by Abstract API. The API has three endpoints which include the following:

"/live": To get live exchange rates between currencies.
"/convert": To get live exchange rates between two or more currencies by specifying a base amount, e.g 5 USD to GBP.
"/historical": To get past exchange rates between currencies within a specific period.

The library will allow developers to communicate with these endpoints through regular Python code. Also, you can use this API without declaring the endpoints every time you need to use it

Project requirements

To take this tutorial, you are required to have a prior knowledge of coding with Python, and concepts such as Object-oriented programming (OOP), Python functions, etc.

You should also understand how to use git, create a Github repository(repo), and push a project to Github.

Tools and Packages

You need the following tools for this guide:

Python: A Python interpreter(>=3.9) for running Python files.
Requests: A Python library used for making HTTP requests.
Abstract API account: You need an AbstractAPI account to access the API key for the Exchange rates API(steps will be provided in the tutorial).
Dotenv: A Python library for handling environment variables.
Poetry: A Python dependency management and packaging tool.

Create a new project.

Follow the steps below to create a new project:

1. Create a new folder using the terminal/command line with the
command below:

mkdir exchangeLibrary

2. Install virtualenv with pip:
Run the command below to installvirtualenv (skip the process if
you have it installed):

pip install virtualenv

3. Change your working folder to the exchangeLibrary folder:

cd exchangeLibrary

4. Create and activate a new virtual environment:
Run the command below to create a env virtual environment:

virtualenv env

Once it has been created, activate it with any of the commands below:

On Windows (Command prompt):

.\env\Scripts\activate

On Linux/macOS:

source env/bin/activate

5. Install required packages:
Run the command below to install required packages:

pip install requests poetry dotenv

6. Open the folder in a code editor like Pycharm/VScode:
This is required to write the code for the library.

Setup project resources

The project’s resources are the necessary folders and files required to build the library. Open up the project in a code editor like Pycharm or VScode.

Do the following to add new files to your project:

1. Create a new folder in your project:
The folder must be named src. In this folder, add a new folder named exchange_python. Also, within the exchange_python folder, add a __init__.py and exchange.py file. Your project file structure should now look like the image below:

The src folder separates the library files from the rest of the project. The exchange_python folder is the main folder which will contain the files required by the Python library. The __init__.py and exchange.py file will contain the library's code (more information on this later).

2. Create a new file in your project:
The file should be named test.py which will be used to write tests for the Python library.

3. Get api key from AbstractAPI:
Follow the steps below to get an API key for the Exchange Rates API:
a. Sign up on AbstractAPI

b. Login to your dashboard
c. Hover your cursor on the left panel of your dashboard
d. Select the Exchange Rates API

e. Get the API key labelled Primary key on the new page.

4. Create environment variables:
Create a new .env file in your project. Add your API key to this file as seen below:

API_KEY=<your-api-key-here>

The file structure for your project should look like the image below:

Build the API wrapper

The next step is to write a Python class as a wrapper for the Exchange Rates API. Each endpoint in this API will be represented as a method within the wrapper. Add the code below to the exchange.py file:

import requests

class ExchangeRatesAPI:
    def __init__(self, api_key):
        self.api_key: str = api_key
        self.__ratesURL: str = "https://exchange-rates.abstractapi.com/v1/"


    def __type_validation(self, type_, arg):
        if not isinstance(arg, type_):
            raise TypeError(f"Expected '{type_}' but got {type(arg).__name__}")

In the code above, the ExchangeRatesAPI class has two attributes - an api-key to authenticate users, and the API's base URL. It also has a __type_validation() method which will be used to validate users’ input. Both the attributes and method are prefixed with double underscore(__). This keeps them private and not easily accessible outside the class.

Although, it is not totally private as there are ways around it. But that is beyond the scope of this tutorial.

Wrap the /live endpoint

This endpoint accepts three request parameters - api-key(required), the base currency code(required), and the target currency code(optional).

The base currency is that currency you want to get the exchange rates for, relative to other currencies. For example, I may want to know the rate at which USD exchanges with other currencies of the world. Therefore, USD is the base currency code.

The target currency code is optional and limits the API response to the selected currencies. For example, CAD to USD, CAD, and GBP. This endpoint will be represented with the live() method. Here is the code below:

import requests

class ExchangeRatesAPI:
    ...
    def live(self, base: str, **kwargs):
        params = {"api_key": self.api_key}
        self.__type_validation(str, base)
        params["base"] = base
        target = kwargs.get("target", None)


        if target:
            self.__type_validation(str, target)
            params["target"] = target


        url = self.__ratesURL + "live"
        response = requests.request("GET", url, params=params)
        json_response = response.json()
        json_response["status"] = response.status_code
        return json_response

In the live() method, the required parameters are set as positional arguments, while optional ones are set as keyword arguments. Type validation is also performed on each argument before they are added to the request parameters.

Finally, a request is sent to the /live endpoint of the API.

Wrap the /historical endpoint

The request parameters are, api-key(required), base currency code(required), date(required) and target currencies' codes(optional).

This is similar to the /live endpoint except that it is dated in the past. The format for the date argument is YYYY-MM-DD. This endpoint will be represented with the historical() method. Below is the code for the method:

import requests

class ExchangeRatesAPI:
   ...
   def historical(self, base: str, date: str, **kwargs):
        params = {"api_key": self.api_key}
        self.__type_validation(str, base)
        self.__type_validation(str, date)
        params["base"] = base
        params["date"] = date


        target = kwargs.get("target", None)


        if target:
            self.__type_validation(str, target)
            params["target"] = target


        url = self.__ratesURL + "historical"
        response = requests.request("GET", url, params=params)
        json_response = response.json()
        json_response["status"] = response.status_code
        return json_response

Wrap the /convert endpoint

The request parameters for this endpoint are api-key(required), base currency(required), target currency(required), date(optional), and base_amount(optional).

The date parameter is passed if you want the results to refer to a date in the past. The base amount is any amount of the base currency you want to convert. For example, 10 USD to CAD, where USD is the base currency and CAD is the target currency.

This endpoint only accepts one target currency per request. It will be represented with the convert() method. Below is the code for this method:

import requests

class ExchangeRatesAPI:
    ...
    def convert(self, base: str, target: str, **kwargs):
        params = {"api_key": self.api_key}
        self.__type_validation(str, base),
        self.__type_validation(str, target)
        params["base"] = base,
        params["target"] = target
        date = kwargs.get("date", None)
        base_amount = kwargs.get("base_amount", None)


        if date:
            self.__type_validation(str, date)
            params["date"] = date

        if base_amount:
            self.__type_validation(str, base_amount)
            params["base_amount"] = base_amount


        url = self.__ratesURL + "convert"
        response = requests.request("GET", url, params=params)
        json_response = response.json()
        json_response["status"] = response.status_code
        return json_response

Note that type enforcement is done for all arguments, e.g base: str. While this may not validate each argument, it helps users know the data type for each argument when using the library.

Test the API wrapper

Bugs are inevitable. Writing tests is important before publishing the library. Python's unittest library will be used to test the ExchangeRatesAPI class. For a complete guide on unittest, read the Beginner’s guide to unit tests in Python. Follow the steps below to test the codebase:

1. Open the init.py file and add the code below:

from .exchange import ExchangeRatesAPI

This allows you to import and use the ExchangeRatesAPI class as
a package and not via a relative file path.

2. Add the code below to the test.py file:

from exchange_python import ExchangeRatesAPI
import unittest
import dotenv
import os

# Configure environment variables
dotenv.load_dotenv()


exchange_api_key = os.environ.get("API_KEY", "")
exchange = ExchangeRatesAPI(exchange_api_key)

class TestExchangeAPI(unittest.TestCase):
    def test_live(self):
        self.assertIsNotNone(exchange.live("USD"))
    def test_convert(self):
        self.assertIsNotNone(exchange.convert("USD", "BRL"))
    def test_historical(self):
        self.assertIsNotNone(exchange.historical("USD", "2022-02-02"))

if __name__ == "__main__":
    unittest.main()

3. Run the test script:
If there are no errors, you should see a message like the one
below in the console:

Deploy the project

This section will show you how to deploy your library

Setup deployment requirements

Follow the steps below to set up deployment requirements:
1. Create a .gitignore file in your project
2. Add the following files to it:

env
.env

3. Create a README.md file and write a brief description about the
library
4. Create a pyproject.toml file in your project

5. Add the following content to this file:

[tool.poetry]
name = “<your python library name>” 
version = "0.1.0"
description = "<a description for the library>"
authors = ["<Your name here> <Your email here>"]
license = "MIT"
readme = "README.md"
repository = "<a link to the your project’s github repo>"
keywords = []
include = [
    { path = "src"}
]

[tool.poetry.dependencies]
python = ">=3.8"
requests = ">=2.32.2"

[build-system]
requires = [
    "poetry-core"
]

build-backend = "poetry.core.masonry.api"

This file contains the configuration details for your library. Fill in the spaces enclosed with these symbols – “<>”. The include variable consists of folders that contain the library files.

6. Proceed to Github to create a new repo.

7. Initialize git in your project with the command below:

git init

8. Connect the repo to your project with the command below:

git remote add origin “https://github.com/<your-github-username>/<your-github-repo-name>”

9. Update the pyproject.toml file with the link to your repo:

repository = "https://github.com/<your-github-username>/<your-github-repo-name>"

10. Push your code to Github.

Deploy the library

Python libraries are deployed on pypi.org. Before you continue, use the search bar on pypi to check if a library with the same name as yours exists.

If you find one, select a different name for your library and update the pyproject.toml file with the new name.

You need to create an account on Pypi to get an api-key for deployment. The following steps will show you how to do this:

1. Sign up and verify your email address:
This is required to complete the registration. A verification link will be sent to your mail.

2. Set up 2 factor authentication:
The 2-factor authentication (2FA) is meant to protect your account. You cannot deploy a Python package without completing this step.

3. Click Generate recovery code to begin THE 2FA:
The final part OF THE 2FA requires an authenticator app to scan a QR code and complete the 2FA

4. Download and configure an authenticator app:
Use an authenticator browser extension like authenticator by authenticator.cc. It works for both Chrome and Edge browsers. Once installed you can use it to scan the QR code from Pypi

5. Get the API token:
Click on the Account settings tab in your dashboard. Scroll to the
bottom of the page to get an API token to deploy your project (click
the Add API token button)

6. Open a terminal/command line in your project (if you are using
VScode) or open your project in a new terminal and activate the
virtual environment.

7. Run the command below to build your package (This will generate a
dist file in your project):

poetry build

8. Set your pypi api token with the command below:

poetry config pypi-token.pypi <your pypi api-token>

9. Publish your library with the command below:

poetry publish

Your Python package will be published on Pypi. You can always find the package in your dashboard or via Pypi’s search bar.

Project maintenance

It definitely does not end here. Overtime, you may need to refactor the codebase or make major changes in your project. After any update, ensure you push the changes to Github.

Run the following commands in the terminal to update the library with the new changes:
a. Activate virtual environment and build the package with the command
below:

poetry build

b. Publish to Pypi:

poetry publish

Note: The pyproject.toml file manages your package’s version with the version variable. You may need to update the version when you make new updates. This is useful to track your package’s version history.
For example, if your project’s version is 0.1.0. You can change it to 0.1.1 or 1.0.0, depending on how you want the version’s progression to be.

Installation and usage

Once the library is published, you can install it by running the command below:

pip install <your-python-library-name>

You can now import the library in your project as seen below:

from exchange_python import ExchangeRatesAPI

Conclusion

In this tutorial, you learnt how to build and deploy a Python library to Pypi. You also learnt how to update your project and re-publish the changes.

Building and deploying a Python library is an exciting process that allows you to share your code with the world. By following the steps outlined in this guide, you now have the knowledge to create, package, and publish your own libraries.

Whether you're solving common problems, providing useful utilities, or simply sharing your unique approach, your contribution helps make Python development more accessible and robust.

Wrap and Render Multiline Text on Images Using Python's Pillow Library

Edun Rilwan — Mon, 13 Jan 2025 12:27:00 +0000

Python takes the lead as a top programming language used for image manipulation. This high-level programming language boasts a vast collection of open-source libraries used in image manipulation and processing. One of such libraries is Pillow.

Pillow is an image processing library in Python commonly used to resize, crop, brighten, or annotate an image. It is popular among developers because of its simplicity and extensive documentation.

However, there is a particular problem with adding text annotations or labels on images using Pillow. Texts often do not wrap to the next line when it gets to the end of the text box. Also, there is no function or
module within the Pillow library that allows you to do this. The only choice is to write the logic to achieve this functionality.

This tutorial will show you how to add a text box where the text wraps to the next line automatically when it gets to the end of the box using Pillow in Python. This functionality will allow you to add text annotations or labels correctly to your images. Below is a final look of what you will build by the end of this tutorial:

The image above is a screenshot of my Dev.to profile which will be used throughout this tutorial. The green text box is the text annotation

Requirements

This tutorial requires you to have a knowledge of basic Python concepts such as conditional statements(if, else), for loops, etc. You also need the following tools and software:

Python3+: A python interpreter for running Python scripts
Pillow: An image manipulation library in Python.
A code editor: A code editor like Pycharm, VScode, etc. to write code.

Create a new project

Follow the steps below to create a new project:

1. Create a new folder using the terminal/command line with the
command below:

 ```
 mkdir image_annotation
 ```

2. Install virtualenv with pip:
Run the command below to install virtualenv (skip the process if
you have it installed):

 ```
 pip install virtualenv
 ```

3. Change your working folder to the image_annotation folder:

 ```
 cd image_annotation
 ```

4. Create a new virtual environment:

 ```
 virtualenv env
 ```

5. Activate the virtual environment with any of the commands below:
On Windows (Command prompt):

 ```
 .\env\Scripts\activate
 ```

 **On Linux/macOS:**

 ```
 source env/bin/activate
 ```

6. Install the Pillow library with the command below:

 ```
 pip install pillow
 ```

Open the project in a code editor, then create a new python file named script.py in the project folder.

Prepare base image

The image you want to annotate is the base image. Open the image and prepare it for annotation using Pillow's ImageDraw module. Write the code below to the script.py file to prepare the base image:

from PIL import Image, ImageDraw, ImageFont
image_file = "path_to_image"

# Open image
image = Image.open(image_file)

# Initialize ImageDraw
draw = ImageDraw.Draw(image)

Annotate the image

Pillow can be used to add both plain text and a text box with a background fill. Also, the text can either be single line or multiline. This tutorial focuses on how to add a multiline text box to an image.

The ImageDraw.multiline_text() method is used to add a multiline text to an image using Pillow. However, this only adds a plain text without a background fill. The ImageDraw.rectangle() method is used to add a text box with a background fill that a body of text can be written on.

Add the code below to the script.py file to draw a multiline text box on your image:

...

# Set text, font, and max width
text = "This is a user profile on dev.to.\n"\
       "It contains the user name, profile picture, and bio"
font = ImageFont.truetype("arial.ttf", 16)  # Use default font if you don't have this
max_width = 200 # Width for the text box

# Calculate positions
x, y = 780, 300  # Starting position for the text box
end_x, end_y = x + max_width, y + 50 # Ending position for the text box


# Dimensions for the background box
background_box = [(x, y), (end_x, end_y)]

# Draw background box
draw.rectangle(background_box, fill="green")


# Draw multiline text
draw.multiline_text((x, y), text, font=font, fill="black", spacing=6)

image.show()

The code above sets the text, text-font, and width for the text box. Also, the x and y variable represents the point from where the drawing should start, while end_x and end_y represents the bottom-right edge of the box. The width and height of the text box are 200 and 50 respectively.

Finally, the ImageDraw.rectangle() and ImageDraw.multiline_text() method are used to draw the text box and a multiline text on the image respectively. The Image.show() method is used to display the processed image. You can save it instead with: image.save("new_image.png"). Below is the result:

There are still some errors with the annotation above. The multiline text should automatically wrap to the next line when it gets to the end of the text box. See how to do this in the next section.

Enable automatic text wrapping

The new line (\n) symbol is used to determine when to move the text to a new line. As seen in the previous example, the body of text after the newline (\n) is moved to the next line. However, in a real life use case where the text length is usually dynamic, it can be difficult to determine where and when to add a newline (\n).

Pillow's ImageDraw module has a .textlength() attribute that can be used to calculate the length of a text. The value can then be compared against the width of the text box to determine where to add a
newline (\n).

Create a new function named wrap_text() at the top of the script.py file (immediately after the import statements). It will contain the logic for the automatic text wrapping. Below is the code for this function:

...

def wrap_text(text, font, max_width, draw):
    """
    Wraps text to fit within the max_width.
    """
    words = text.split()
    lines = [] # Holds each line in the text box
    current_line = [] # Holds each word in the current line under evaluation.

    for word in words:
        # Check the width of the current line with the new word added
        test_line = ' '.join(current_line + [word])
        width = draw.textlength(test_line, font=font)
        if width <= max_width:
            current_line.append(word)
        else:
            # If the line is too wide, finalize the current line and start a new one
            lines.append(' '.join(current_line))
            current_line = [word]

    # Add the last line
    if current_line:
        lines.append(' '.join(current_line))

    return lines

...

In the wrap_text() function, the body of text is split into its individual words. The length of the first word is checked against the text-box's width. If the word length is lesser, it is added to
the current_line list. Subsequently, each word is added to this list, combined with the existing ones, then everything is checked against the text-box's width.

If a new word causes the entire text length to be greater than the box's width, the word is moved to the next line. The same logic is applied to the next line until the entire body of text is displayed on screen.

Finally, the lines list is returned after the last line has been added. Add the code below immediately after the text, font, and max_width variables:

...
# Wrap text into lines
wrapped_lines = wrap_text(text, font, max_width, draw)
...

Where text is the body of text to be added, font is the text font, max width is the box's width, and draw is an instance of the ImageDraw module.

Replace the draw.multiline_text() method with the code below:

...

description = ""
for line in wrapped_lines:
    description += line + "\n"


# Draw multiline text.
draw.multiline_text((x, y), description, font=font, fill="white", spacing=6)

...

Remove the new line* (\n)* symbol from the text and run the code:

text = "This is a user profile on dev.to. It contains the user name, profile picture, and bio"

The result of this code will be a text annotation that still overflows the box's height. While the text can now automatically adjust with the text box's width, the box's height remains fixed which causes the text to overflow outside the box.

Set up a dynamic box height

A dynamic box height is one that is determined by the number of lines occupied by the text. The first step is to change the box's end_y variable to a dynamic value as seen in the code below:

...
end_x, end_y = x + max_width, y + (24 * int(len(wrapped_lines))) # Ending position for the text box
...

The equation - y + (24 * int(len(wrapped_lines))) was arrived at after a couple of trials. It appeared to be the best solution to get a dynamic box height for this use case. The wrapped_lines list contains all the lines to be added to the text box, therefore, the length of this list equals the total lines of text for the text box.

Below is the result:

You may need to multiply the total lines by different values to get a perfect solution for your use case.

NOTE: Difference in spacing, font size, etc. affects the equation. For example, this tutorial uses a font size of 16. If your project uses a different font-size, you will need to tweak the values used in the equation to get a dynamic box height that fits your use case.

Add text padding

Also, the text is too close to the box's corners affecting its readability and style. This can be corrected by padding the text within the box. Add a new padding variable to the script.py file and change the text box dimension. Here is the code below:

...
padding = 10

background_box = [(x - padding, y - padding), (end_x + padding, end_y + padding)]
...

This code allows for spacing between the text and the box's corners as seen in the image below:

Add a pointer

A pointer makes it easy to determine which part of the image the annotation/label is meant for. The pointer should come before the annotation. This means the pointer will be drawn on the text box's current position, while the text box will shift to the right.

Therefore, the x axis for the text box will be tied to a new box_x variable. This change must also reflect in other variables where the box's x axis is used. Here is the updated code below:

# Calculate positions
x, y = 780, 300  # Pointer position
box_x = 780 + 30 # Box starting x position
padding = 10 # Text padding
end_x, end_y = box_x + max_width, y + (24 * int(len(wrapped_lines))) # Ending position for the text box


# Calculate total height for the background
background_box = [(box_x - padding, y - padding), (end_x + padding, end_y + padding)]


# Draw Pointer
draw.circle((x, y), 10, fill="green")

# Draw background rectangle
draw.rectangle(background_box, fill="green")

description = ""
for line in wrapped_lines:
    description += line + "\n"


draw.multiline_text((box_x, y), description, font=font, fill="white", spacing=6)

image.show()

In the code above, the ImageDraw.circle() method, where 10 is the radius, is used to draw the pointer at the specified point. The box_x variable is the new value for the box's x axis.

Below is the final code for the script.py file:

from PIL import Image, ImageDraw, ImageFont


def wrap_text(text, font, max_width, draw):
    """
    Wraps text to fit within the max_width.
    """
    words = text.split()
    lines = [] # Holds each line in the text box
    current_line = [] # Holds the current line under evaluation.

    for word in words:
        # Check the width of the current line with the new word added
        test_line = ' '.join(current_line + [word])
        width = draw.textlength(test_line, font=font)
        if width <= max_width:
            current_line.append(word)
        else:
            # If the line is too wide, finalize the current line and start a new one
            lines.append(' '.join(current_line))
            current_line = [word]

    # Add the last line
    if current_line:
        lines.append(' '.join(current_line))

    return lines



image = Image.open("practise.png")
draw = ImageDraw.Draw(image)


# Set text, font, and max width
text = "This is a user profile on dev.to. It contains the user name, profile picture, and bio"
font = ImageFont.truetype("arial.ttf", 16)  # Use default font if you don't have this
max_width = 200

wrapped_lines = wrap_text(text, font, max_width, draw)

# Calculate positions
x, y = 780, 300  # Pointer position
box_x = 780 + 30 # Box starting x position
padding = 10 # Text padding
end_x, end_y = box_x + max_width, y + (24 * int(len(wrapped_lines))) # Ending position for the text box


# Calculate total height for the background
background_box = [(box_x - padding, y - padding), (end_x + padding, end_y + padding)]


# Draw Pointer
draw.circle((x, y), 10, fill="green")

# Draw background rectangle
draw.rectangle(background_box, fill="green")

description = ""
for line in wrapped_lines:
    description += line + "\n"


draw.multiline_text((box_x, y), description, font=font, fill="white", spacing=6)

image.show()

Conclusion

Image manipulation is not always as difficult as it may seem. While some image manipulation libraries cannot directly solve your problem with their modules, you can implement a specific solution for your use case using the available modules. That is the beauty of coding - The ability to solve problems with custom and specific solutions.

In this tutorial, you learnt how to use Python's Pillow library to annotate an image, add a multiline text box that automatically wraps to the next line, etc. You also learnt how to write mathematical equations that can help you with image manipulation.

Refer to the Pillow documentation for detailed explanation on each module used.

How to view API request examples in a ReadMe documentation.

Edun Rilwan — Mon, 30 Dec 2024 19:07:16 +0000

Request examples are more than a mere addition to API documentation. They are necessary to easily onboard developers and increase API adoption. They cut development time by helping developers discover how to make a successful request to your API endpoints.

Imagine a Fintech API like Plaid without request examples in the API documentation. Their customer service will have to deal with complaints from frustrated developers each day. Eventually, developers will abandon their service for a better alternative.

My recent experience with The Movie Database (TMDB) API documentation underscores the importance of request examples in API documentation. It took me a couple of hours to figure out how to make a successful request to an endpoint because I couldn't access a request sample. However, I eventually found it in an unexpected place. ReadMe on the other hand didn't make it easy.

The Problem

Certain endpoints in the TMDB API require a RAW_BODY body parameter as seen in the image below:

Without a request sample, it is difficult to come up with the correct json data. Although, you may end up with a solution after a few google search, which is not a good user experience.

The solution

A glance at an endpoint page on ReadMe, there is no sight of a request sample. Despite being a very important part of API documentation, ReadMe didn't do a good job to make it easily accessible.

You can view a request sample for an endpoint on ReadMe through the steps below:

Click on the EXAMPLES field on the right and select the Request Example option.
The request sample will be displayed as seen in the image below:

That's all it takes to view a sample request in a ReadMe documentation.

NOTE: A request sample will be available provided that the API documentation writer(s) add it to the documentation.

Conclusion

This short article is useful for developers who may have to use an API with its documentation on ReadMe. If you also plan to use the TMDB API, this article will help you view sample request for each endpoint.

Building SaaS Faster with Ercas for SaaS: A Template for Indie Hackers

Edun Rilwan — Tue, 17 Dec 2024 09:27:49 +0000

Introduction

Indie hacking thrives on launching ideas quickly, but backend developers, especially in Nigeria, face significant challenges: limited resources, complex payment integrations, and the steep learning curve of building robust subscription systems. These issues slow down the journey from concept to execution.

Ercas for SaaS (EFS), a Reflex.dev template is designed to simplify subscription and payment management for SaaS applications. This template empowers developers with pre-built authentication, subscription logic, and payment integration with the ErcasPay API, reducing development time and enabling faster launches.

This article demonstrates how to use the template, highlighting its features and offering a step-by-step guide to help developers kick-start their SaaS projects.

Key features

Subscription Management: The plug-in supports monthly plans with start and end dates, renewal logic, and plan expiry handling.
Payment Integration: It also contains pre-configured payment handling using ErcasPay API for secure transactions.
User Authentication: Ready-made sign-up and login functionality for user management.
Customizable Pricing Pages: Functional pages that require minimal styling knowledge.
Scalability: The best part is the modular design that allows you to add features and customize the project as your SaaS grows.

Project requirements

The following is required for this project:

Python 3.8+: It is required to run your Python code
reflex: A Python framework for building full-stack web apps using Python code (installation steps will be provided in the tutorial)
Basic knowledge of Python and usage of the reflex Python web framework.
Access to the ErcasPay API and API token. Create an account on ErcasPay to get an API token. You can also access the docs here.

How to install EFS

Follow the steps below to install EFS to your local environment:

Create a new folder using the terminal or command prompt with the
command below:
```
mkdir saas_project
```
Open this folder with the command below:
```
cd saas_projectb
```
Clone the Ercas-for-saas repository on Github with the command
below:
```
git clone https://github.com/Omotunde2005/Ercas-for-saas.git
```

This will create a new folder named Ercas-for-saas in the saas_project folder. Open the Ercas-for-saas folder in a code editor like Vscode or Pycharm (Preferrably Vscode).

Understanding the project files

The Ercas-for-saas folder has a file structure like the one below:

assets/
   favicon.io
ercas_saas/
   components/
       __init__.py
       container.py
   pages/
       __init__.py
       dashboard.py
       home.py
       login.py
       pricing.py
       signup.py
   state/
       __init__.py
       app.py
       auth.py
       base.py
   __init__.py
   ercas_api.py
   ercas_saas.py
   models.py
.gitignore
ReadMe.md
requirements.txt
rxconfig.py
test.py

These files are arranged according to the reflex app file structure. Read this guide to get a grasp of reflex file structure and an overview of the reflex framework. Each folder and their content are quite self-explanatory. But for clarity, let's explore the main folders and their files:

The ercas_saas folder is where you will work with the most. It contains your app pages, database models, styling, etc.
The components folder contains a reflex component that is used within the plug-in.
The pages folder contains the web templates frequently used in Saas applications (dashboard, home, login, pricing, signup). The code comments in each file will guide you on what each function or utility does.
The state folder contains the States used in the app. Read more about states in Reflex here.
The ercas_saas.py file is the main file for your app. You can add each page in your app directly in this file. This allows you to keep track of each web page in your app.
The ercas_api.py file is the API client for the ErcasPay API. It handles all requests to the ErcasPay API which allows you to receive payments from users and verify their subscriptions.
The models.py file contains information about the database model and schema.

How to run the EFS plug-in locally

Open the EFS project in the terminal. and follow the steps below to run the EFS plug-in locally:

Create a new virtual environment with virtualenv in Python
(install virtualenv if you do not have it):
```
virtualenv env
```
Activate the virtual environment:
Windows:
```
.env\Scripts\activate
```
Linux/macOS
```
source/bin/activate
```
Install the project requirements with the command below:
```
pip install -r requirements.txt
```
Install passlib[bcrypt] package for password hashing with the
command below (This was not included in the requirements.txt
because it has a special installation process):
```
pip install passlib[bycrypt]
```
Initialize reflex with the command below
```
reflex init
```
This will create a new .web folder in the project. This
folder will contain the frontend requirements for your app. In most
cases, you won't have to work with this folder. Reflex handles the
frontend for you.
Create a new database from the existing schema with the command
below:
```
reflex db init
```
This will also create a new saas.db file in your project.
Create a new .env file for environment variables like the
ErcasPay API token. It is used within the app to authenticate with
the API. For a start, get a test API token by setting up your
account on ErcasPay.
Finally, run the project with the command below:
```
reflex run
```

The project will run on port 3000 by default so you can access it at http://localhost:3000/ on your pc.

Editing and customization

The project contains ready-made templates which you can customize to your specific needs. Example customization includes, adding new pages, fonts, styling, etc. Checkout the reflex documentation for more ideas.

Conclusion

Ercas for SaaS is a powerful tool for indie hackers and developers looking to launch SaaS applications quickly. By leveraging the Reflex.dev template, you can bypass the complexities of authentication, payment, and subscription management. This tutorial has shown you how to install, run, and customize the project, empowering you to focus on building great software rather than reinventing the wheel.

Start using Ercas for SaaS today and accelerate your journey to SaaS success!

How to build a fully-fledged telegram bot in Python

Edun Rilwan — Fri, 31 May 2024 22:53:37 +0000

Introduction

Chatbots are gradually becoming an integral part of our lives. These automated agents allow users to solve problems quickly by engaging them in real-time. I personally refer to them as online-buddies.

One of the simplest ways of building a chatbot is through the Telegram messaging app. Telegram provides an easy way to build chatbots through their API.

In this article, you will understand how telegram bots work and how to create a Telegram bot using Python.

By the end of this article, you would have built a fully-fledged currency exchange telegram bot with Python.

This telegram bot allows users to get the exchange rate between two or more currencies in real time. It will also store registered users’ data in a SQL relational database.

NB: This is not your regular kind of bot. You will build a fully-fledged telegram bot in Python that uses a relational database.

The following are the features of the bot:

The bot registers new users and stores their data in a relational database.
Only registered users can get the exchange rate between two or more currencies.
Users can select a favorite base currency and multiple target currencies they would like to get updates on.
The bot sends daily updates on latest exchange rates based on a user's base currency and their target currencies.
Users can activate or deactivate the daily updates.

The purpose of this tutorial is to help you learn how to build a fully-fledged Telegram bot in Python. In the process, you will also learn concepts such as OOP, decorators, etc. that will help you write cleaner and reusable code in Python.

PS: This article explores the conceptual aspect of Telegram bots in details.

Below is a live demo of the bot in action:

Requirements

Below is a list of tools and libraries required for this tutorial:

Python: Python must be installed on your computer. Preferably, Python 3.8+. You must also have a basic knowledge of Python.

python-telegram-bot library (PTB): PTB library would be used to build the telegram bot. It is a feature-rich wrapper for the Telegram bot API in Python. To install this library, run the command below:

pip install python-telegram-bot

Python-telegram-bot[job_queue]: job_queue is a package within the PTB library. It is used for setting up cron-jobs such as reminders, etc. in a telegram bot. Run the command below to install it:

pip install python-telegram-bot[job_queue]

sqlalchemy library: sqlalchemy is a Python library used for creating a relational database. Run the command below to install this library:

pip install sqlalchemy

Requests library: This library is used for making HTTP requests in Python. In this tutorial, it would be used to send HTTP requests to the currency exchange API. Run the command below to install it:

pip install requests

A telegram bot: This can be created on the telegram app. It lets you create and customize the theme and design of your chatbot. Once created, you would be given an api-token that would let you authenticate with the API.

Abstract API api-key: Abstract API offers a suite of 12+ REST APIs. The currency exchange API is one of these APIs. You need an api-key to be able to use the API. You can only get one when you sign up with Abstract API.

Create a Telegram bot

As part of the requirements for this tutorial, the following is a step-by-step process to create and design a Telegram bot:

Open the Telegram app.
Enter the name BotFather in the search bar.
Click on the BotFather profile like the one in the image below:

Click the start button in the new chat that opens.

Follow the directions of the BotFather to create and design your Telegram bot.

BotFather is the father of all Telegram bots. It was created by Telegram to help developers create chatbots on the platform.

Create an Abstract API account

Abstract API offers a single api-key for registered users to authenticate with any of their APIs. Below is a step-by-step process to create an Abstract API account:

Proceed to their sign-up page.
Enter your details and confirm you’re not a robot.

Click the Continue button to complete your registration.

A confirmation link will be sent to your mail. This link will confirm your registration and redirect you to their login page.

Once you login, you will have access to your dashboard.

Get your Abstract API key

Follow the steps below to get your api-key:

Hover your cursor around the left side of your dashboard.
Select Exchange Rates under APIs to lookup.
Click Try it out on the new page.
Locate the Primary key label. You will find your api-key there.

Build the Telegram bot

There are various libraries used for building a Telegram bot in Python. One of which is the python-telegram-bot (PTB) library.

Its use of asynchronous programming enables your bot to handle multiple requests at a time without blocking the other.

Also, it has a bunch of other features for building a fully functional Telegram bot. You will explore most of these features in this tutorial.

Open your code editor. Ensure you have created a project and a virtual environment that has all the required libraries installed in it.

Initial application setup

The first step is to configure the bot settings. Below is the code for the application setup:

from telegram.ext import ApplicationBuilder


# To ensure errors are properly logged
logging.basicConfig(
   format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
   level=logging.INFO
)

# The "main block"
if __name__ == "__main__":

   TOKEN = 'your-api-token'

   # An application instance
   application = ApplicationBuilder().token(TOKEN).build()

In the code above, the logginglibrary is used to ensure that errors from the bot are logged with correct descriptions so users can easily track and resolve them.

Also, an application instance is created with the ApplicationBuilder() class of the PTB library. It uses the .token() and .build() method to create an application instance that authenticates your bot with Telegram API.

The .token() method accepts a compulsory TOKEN argument, that is, your telegram api-token.

This initial setup is required for every bot (also known as application) built with the PTB library.

Create the start command

The first command available to users in a Telegram bot is the /start command. Commands are instructions given by users to the bot.

Therefore, you need to create a function that responds to this command.

Follow the steps below to create a function for the /start command:

Import the following modules from PTB library

import telegram
from telegram import Update
from telegram.ext import ApplicationBuilder, ContextTypes, CommandHandler, filters

Write the function for the start command

...
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):

   # Responds to a user
   await context.bot.send_message(
       chat_id=update.effective_chat.id,
       text="Welcome to the currency exchange bot.\n\n"
            "What is your base currency? Enter your answer using the example
below as a guide:\n\n"
            "/baseCurrency\n"
            "your base currency, e.g USD, GBP\n\n"
   )
...

The start() function is an asynchronous function that accepts two arguments namely:

update: This argument has a type hint of the Update class in PTB library. It contains updates like new messages from the bot. It also includes data about the sender, such as: name, chat_id, etc.
context: This argument has a type hint of the ContextTypes.DEFAULT_TYPE module in PTB. It includes all actions the bot can perform, such as sending messages, audios, replying to messages, etc.

These two arguments are compulsory for every function in the PTB library.

The context.bot.send_message() method is used to send messages to users. It accepts two compulsory arguments which include the following:

chat_id: A unique identifier for the user/chat to send the message to.
text: The textual content of the message.

The start() function is invoked when a user starts the bot. In the case of the currency exchange bot, it asks a few questions from them to ensure a personalized experience.

This question is added to the .send_message() method in the start() function above.

Register the start command

Handlers in the PTB library provide a way of linking each command to a function. Each function is executed when its linked command is invoked.

For example, when building a Django web app, you need to create url paths and a view function for each path. When a user visits any url, its associated view function is executed.

Add a handler for the start() function below the application instance and start the bot:

...
if __name__ == "__main__":

   TOKEN = 'your_api_token'
   application = ApplicationBuilder().token(TOKEN).build()

   # Creates a command handler
   start_handler = CommandHandler('start', start)

   # Adds the handler to the bot
   application.add_handler(start_handler)

   # start the bot. 
   application.run_polling()

The CommandHandler() class is used to link a command and a function together. It accepts two arguments — the command name and the function.

You register the handler with the application using the .add_handler() method.

The application.run_polling() method keeps the bot running and constantly polls the Telegram bot API for new alerts on your bot. It should be at the bottom end in the main block.

Finally, run the script file to start the bot.

Open your Telegram bot and click on the start button in the chat. The bot will respond with the message that was set earlier in the start() function. This means the bot setup was successful. Below is an example:

Learn more about setting up an application and creating functions in this sample tutorial of the PTB documentation.

Create a database connection

A database is required to store users' data. The sqlalchemy library in Python will be used to set up the database.

For this tutorial, you will use a local database file which is suitable for a development environment.

Follow the steps below to set up a database:

Create a new file named database.py
Open the file and add the code below:

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
import os
# The database url
SQLALCHEMY_DATABASE_URL = "sqlite:///users.db"
# Creates a database engine
engine = create_engine(
   SQLALCHEMY_DATABASE_URL
)

# Handles database sessions
SessionLocal = sessionmaker(bind=engine)

Base = declarative_base()

The following is an analysis of the database.py file:

SQLALCHEMY_DATABASE_URL: This refers to the database link or URL. Since you would be using a local database file, the URL would be a local file name. For this tutorial, the database file is titled users.db
create_engine(): This is a method in sqlalchemy that is used to create connections with a database. It takes the database URL as an argument.
SessionLocal: SessionLocal object is used for creating sessions in SQLAlchemy. It is used to manage transactions and serve as a gateway to the database.
Base: This line creates a base class for declarative class definitions. In SQLAlchemy, a declarative base is a base class for declarative class definitions, which are used to define database models.

Create a database model

The next step is to create a User database model. Follow the steps below to create a database model:

Create a new file named models.py
Add the code below to this file:

from sqlalchemy import Boolean, Column, Integer, String
from database import Base

class User(Base):
   __tablename__ = "users"

   id = Column(Integer, primary_key=True, index=True)
   chat_id = Column(Integer, unique=True, nullable=False)
   base_currency = Column(String, unique=False, nullable=False)
   currency_pairs = Column(String, unique=False, nullable=False)
   receive_updates = Column(Boolean, nullable=False, unique=False, default=False)

The _User _model contains the following columns:

chat_id: A long set of integers such as, 257945683925 that is unique to each chat or user.
base_currency: This column is for a user's favorite base currency such as, USD, CAD, etc.
target_currencies: This refers to a list of other currencies the user would like to get daily updates on, relative to their base currency. For example, a user can select USD as their base currency and GBP, CAD, EUR as their target currencies. This means that the user would like to get daily updates on how much 1USD is, when converted to GBP, CAD, and EUR.
receive_updates: This is a boolean field that records if the user would like to receive updates or not.

Create the database file

Follow the steps below to create a new database file:

Open the main.py file.
Add the following import statements:

from database import Base, SessionLocal, engine
from models import User
...

Add the code below after the logging.basicConfig() function.

...
Base.metadata.create_all(bind=engine)
db = SessionLocal()
...

Run the script file.

The steps above will create a database file and add a _user _ table to it. An instance of the database session is assigned to the db variable. It is used to perform CRUD (create, read, update, delete) operations with the database.

A new file named users.db would be created in your project folder.

Create a CurrencyExchange class

So far, you have learnt the following:

How to create a telegram bot and get an api-token.
How to create a command and a corresponding function in PTB.
How to register a command with a function through handlers.
How to create a database connection.
How to add a database model in Python.
How to create a relational database file in Python.

The currency exchange API is a REST API with different endpoints. In order to prevent repetition and enhance readability, it is necessary that you bundle all the endpoints into a Python class.

This is a concept in Object-Oriented Programming (OOP). You can check out my complete guide on OOP for beginners.

The class will be named CurrencyExchange.

Follow the steps below to create the CurrencyExchange class:

Create a new file named exchange.py
Add the code below to create the class:

import requests

class CurrencyExchange:

   def __init__(self, api_key):
       self.key = api_key
       self.codes = ["ARS", "AUD", "BCH", "BGN", "BNB", "BRL", "BTC", 
                     "CAD", "CHF", "CNY", "CZK", "DKK", "DOGE", "DZD", 
                     "ETH", "EUR", "GBP", "HKD", "HRK", "HUF", "IDR", 
                     "ILS", "INR", "ISK", "JPY", "KRW", "LTC", "MAD", 
                     "MXN", "MYR", "NOK", "NZD", "PHP", "PLN", "RON", 
                     "RUB", "SEK", "SGD", "THB", "TRY", "TWD", "XRP", 
                     "ZAR", "USD"]

   # Performs one-to-one exchange
   def single_exchange(self, params):
       url = "https://exchange-rates.abstractapi.com/v1/convert"
       params['api_key'] = self.key
       res = requests.request("GET", url, params=params)
       return res.json()

   # Performs one-to-many exchange
   def multiple_exchange(self, params):
       url = "https://exchange-rates.abstractapi.com/v1/live"
       params['api_key'] = self.key
       res = requests.request("GET", url, params=params)
       return res.json()

   # validates a single currency code
   def is_valid_currency(self, currency):
       if currency in self.codes:
           return True
       else:
           return False

   # validates multiple currencies
   def is_valid_currencies(self, currencies_list):

       # uses all() function to loop through currencies list
       if all(currency in self.codes for currency in currencies_list):
           return True
       else:
           return False

The CurrencyExchangeclass has two attributes - an api_key and currency codes which are supported by the bot.

The single_exchange() method is for exchange rate between two currency pairs. It uses the convert endpoint of the currency exchange API.

The multiple_exchange() method is for rates between a single base currency and multiple target currencies. It uses the live endpoint of the currency exchange API.

The last two methods namely is_valid_currencies() and is_valid_currency() will be used to validate user inputs. That is, single and multiple currency codes respectively.

Read the API documentation to learn more about these endpoints.

Add new functions and commands

The next step is to add new commands and their corresponding functions to the bot.

Create function for base currency input

This function receives and records users' base currency. Users have been instructed in the start() function to submit a base currency code through the /baseCurrency command.

Commands in the PTB library accept arguments as user inputs. It is like a URL with query parameters.

Below is the function for the /baseCurrency command:

...

async def record_base_currency(update: Update, context: ContextTypes.DEFAULT_TYPE):
   """ Record Base Currency """

   # user input
   argument = "".join(context.args)
   base_currency = str(argument).upper()

   # validates the user input(currency code)
   if currency_exchange.is_valid_currency(base_currency):
       context.user_data["base_currency"] = base_currency
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text="Kindly list your favorite target currencies. That is, a list of currencies you want to get updates on relative to your base currency."
                " You can select as many as you want\n"
                "<b>Each currency should be separated by a comma(,)</b>\n\n"
                "Use the example below as a guide:\n\n"
                "/targetCurrencies\n"
                "USD,CAD,GBP",
           parse_mode=telegram.constants.ParseMode.HTML
           )
   else:
       # alerts user if currency is not supported 
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text=f"This bot does not support {base_currency} currency"
       )

...

Arguments in PTB are stored in a Python list called context.args.

In the record_base_currency() function, this list is unpacked and converted to a string. This string, which is the user's base currency, is converted to uppercase and stored in the context dictionary.

A context dictionary is used to temporarily store information within the bot’s memory. It is of two types:

The bot context dictionary: It stores information temporarily in memory and it can be accessed from each user's chat. More like a private storage.
The user context dictionary: It stores information temporarily in memory, and it can only be accessed in a single user's chat. More like a private storage.

Instead of adding user's input directly to the database, you can easily add it to the context dictionary. This helps in the following ways:

It helps to limit frequently queries to the database.
In case the user fails to complete registration, you do not have a redundant or incomplete record in the database.

If the user successfully completes his/her registration, you can then add everything to the database.

The bot queries the user for their target currencies. Each user input is verified to ensure that it is supported by the API.

PTB library allows the bot to send HTML messages. Telegram API has a list of supported HTML tags.

When sending HTML messages, it is important that you parse the message by adding the parse_mode argument to the context.bot.send_message() method.

Below is an example of the /baseCurrency command:

Create function for target currencies input

In the previous step, the user is prompted to submit their target currencies. The record_target_currencies() function will be used to validate and record the data submitted by the user.

Follow the steps below to create this function:

Open the main.py file
Import the following classes

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, ReplyKeyboardMarkup

Add the new function below:

...
async def record_target_currencies(update: Update, context: ContextTypes.DEFAULT_TYPE):
   # user input
   arguments = "".join(context.args)

   currency_pairs = arguments.split(",")

   # validates the target currencies
   if currency_exchange.is_valid_currencies(currency_pairs):
       context.user_data["target_currencies"] = arguments

       keyboard = [[InlineKeyboardButton('Yes', callback_data='yes')],
                   [InlineKeyboardButton('No', callback_data='no')]]

       await update.message.reply_text(
           text="<b>Would you like to receive daily updates on selected currencies?</b>",
           parse_mode=telegram.constants.ParseMode.HTML,
           reply_markup=InlineKeyboardMarkup(keyboard)
       )

   else:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text=f"Error occurred! Ensure that each currency is supported by the bot."
       )
...

In the code above, the record_target_currency() function adds the user input directly to the context dictionary. The function also validates a user input before adding it to the context dictionary.

If submission is successful, the user is asked if they want to receive daily updates. The InlineKeyboardButton() and InlineKeyboardMarkup() classes are used to create a list of clickable options for a user to select from.

Below is a sample of the /targetCurrencies command and the bot's response:

Create function to complete user registration

In the previous function, the user is presented with a list of options to choose from.

The complete_registration() function receives the user's selection. It enters this selection alongside the previous inputs submitted by the user into the database.

This marks the end of the user registration. Below is the code for this function:

async def complete_registration(update: Update, context: ContextTypes.DEFAULT_TYPE):
   """ User completes registration """
   query = update.callback_query.data

   # checks for incomplete registration
   try:
       target_currencies = context.user_data.get("target_currencies")
       base_currency = context.user_data.get("base_currency")
   except KeyError:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text="<b>There's an error with your registration. Kindly restart by submitting your base currency</b>\n"
                "Use the example below as a guide:\n\n"
                "/baseCurrency\n"
                "your base currency, e.g USD, GBP\n\n",
           parse_mode=telegram.constants.ParseMode.HTML
       )
   else:
       if query == "yes":
           receive_updates = True
       else:
           receive_updates = False

       new_user = User(
           chat_id=update.effective_chat.id,
           base_currency=base_currency,
           currency_pairs=target_currencies,
           receive_updates=receive_updates
       )
       db.add(new_user)
       db.commit()

       options = [["Activate Updates 🚀", 'Deactivate updates'], ['Bot Manual 📗']]

       key_markup = ReplyKeyboardMarkup(options, resize_keyboard=True)
       await context.bot.send_message(text="<b>You have successfully completed your registration</b>",
                                      reply_markup=key_markup,
                                      chat_id=update.effective_chat.id,
                                      parse_mode=telegram.constants.ParseMode.HTML)

In the code above, all the previous entries are retrieved and added to the database. The user gets a success message and three buttons are added to the bot. This would allow the user to perform certain tasks quickly. Below is an image of the three buttons:

In some cases, it is possible the user omitted a step in the registration process.

For example, if a user has a prior knowledge of how this bot works, he/she could decide to start the bot and enter the target_currencies first and skip the base_currency part.

If by the end of the registration, you try to access the value for the base_currency from the context dictionary, it will trigger a KeyError because it doesn't exist. This function handles this scenario.

Create function for messages

Users now have full access to the bot. You need to add a function that handles the user's direct messages to the bot.

For this tutorial, the only direct messages the bot can respond to are those from the 3 buttons. If you click on any of them, a direct message will be sent to the bot.

Below is the function that handles direct messages to the bot:

...
async def direct_messages(update: Update, context: ContextTypes.DEFAULT_TYPE):
   """ Direct messages """
   message = update.message.text
   user = db.query(User).filter_by(chat_id=update.effective_chat.id).first()

   if message == "Bot Manual 📗":
       await context.bot.send_message(
           text="<i>Click <b>Activate Updates</b> to activate daily updates</i>\n\n"
                "<i>Click <b>Deactivate Updates</b> to deactivate updates</i>\n\n"
                "<i>Click <b>Bot Manual</b> to learn how to use the bot</i>\n\n"
                ""
                "<i>To find the exchange rate between a base currency and multiple target currencies, use the command "
                "below:\n\n</i>"
                "/multipleExchange\n"
                "USD/CAD/EUR\n\n"
                "Put your base currency first and other currencies should follow. Separate them with a forward "
                "slash(/)\n\n"
                ""
                "<i>To find the exchange rate between a base currency a single target currency, use the command "
                "below:</i>\n\n"
                "/singleExchange\n"
                "USD/GBP\n\n"
                "Put your base currency first and the target currency should follow. Separate them with a forward "
                "slash(/).\n\n"
                ""
                "<i>To find the exchange rate between a base currency a single target currency with a base amount, "
                "use the command below:</i>\n\n"
                "/exchangeRate\n"
                "USD/CAD @ 50\n\n"
                "Put your base and target currency together and signify the base amount with the @ symbol",
           chat_id=update.effective_chat.id,
           parse_mode=telegram.constants.ParseMode.HTML)

   elif message == "Activate Updates 🚀":
       user.receive_updates = True
       db.commit()
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text="<i>You have successfully activated daily exchange rate updates</i>",
           parse_mode=telegram.constants.ParseMode.HTML
       )

   elif message == 'Deactivate updates':
       user.receive_updates = False
       db.commit()
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text="<i>You have successfully deactivated daily exchange rate updates</i>",
           parse_mode=telegram.constants.ParseMode.HTML
       )

   else:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text="<i>This bot is not able to respond to your messages for now</i>",
           parse_mode=telegram.constants.ParseMode.HTML
       )
...

In the code above, each button click is handled by the bot. The Bot manual sends a guide on how to use the bot, the Activate updates activate daily updates, and Deactivate updates deactivates daily updates from the bot. You can add as many buttons as you like.

Create function for single exchanges

The function of this bot is to help users get exchange rates in real time. It does this in 3 ways. They include:

single exchange - that is, between two currencies. For example: USD-CAD.
multiple exchange - that is, between one currency and other multiple currencies. For example: USD to CAD/BTC/AUD, etc.
arbitrary exchange - that is, exchange between two currencies while stating a base amount. For example: 50 USD to CAD.

Using the single_exchange() method of the CurrencyExchange class, the function below allows users to find single exchange rates:

...
async def single_exchange_rate(update: Update, context: ContextTypes.DEFAULT_TYPE):
   """ Exchange Currencies """
   currency_pairs = "".join(context.args)

   # Ensures the currency codes are split by a slash(/)
   try:
       base_currency = currency_pairs.split("/")[0].upper()
       target_currency = currency_pairs.split("/")[1].upper()
   except IndexError:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text=f"Error occurred! You must enter two currency codes separated by a forward slash(/)"
       )
   else:
       # validates currency codes
       if currency_exchange.is_valid_currency(base_currency) and currency_exchange.is_valid_currency(target_currency):
           params = {
               "base": base_currency,
               "target": target_currency
           }

           response = currency_exchange.single_exchange(params=params)
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text=f"<b>Base Currency:</b> {base_currency}\n"
                    f"<b>Target Currency:</b> {target_currency}\n"
                    f"<b>Exchange Rate</b>: {response['exchange_rate']}\n\n"
                    f"<i>This means that 1 {base_currency} is equal to {response['exchange_rate']} {target_currency}</i>",
               parse_mode=telegram.constants.ParseMode.HTML
           )

       else:
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text=f"Error occurred! Ensure that both currencies are supported by the bot."
           )
...

The user is instructed to use the /singleExchange command to make a request and separate the two currency codes by a slash (/). This input is split by the slash and assigned to two different variables.

They are passed as parameters into the single_exchange() method. The response is styled with HTML and sent to the user.

Using error handling, the function ensures that the user input is in the right format and contains currency codes that are supported by the API.

The image below shows how to send a single exchange command:

Create function for multiple exchanges

This section shows you how to handle multiple or one-to-many exchange rates for users. Users are to separate the currency codes by a comma, with the base currency added first.

Below is the code below for this fucntion:

...
async def multiple_exchange_rate(update: Update, context: ContextTypes.DEFAULT_TYPE):
   """ Exchange Currencies """

   # user input
   argument = "".join(context.args)
   currency_pairs = argument.split("/")


   # ensures currency codes are split 
   try:
       base_currency = currency_pairs[0]
       target_currencies_list = currency_pairs[1:]
   except IndexError:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text=f"Error occurred! Ensure that there are more than two currencies separated by a forward slash(/)."
       )
   else:
       # validates currency codes.
       if currency_exchange.is_valid_currencies(target_currencies_list):
           print(target_currencies_list)
           target_currencies = ",".join(target_currencies_list)

           # API request parameters
           params = {
               "base": base_currency,
               "target": target_currencies
           }
           # API response
           response = currency_exchange.multiple_exchange(params=params)
           result = []
           for currency in target_currencies_list:
               rate = response["exchange_rates"][currency]
               result.append(f"<b>{currency}</b> = {rate}\n")

           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text="".join(result),
               parse_mode=telegram.constants.ParseMode.HTML
           )

       else:
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text=f"Error occurred! Ensure this bot supports the currencies you entered."
           )
...

This function is similar to the single_exchange() function, except that it queries multiple currency codes at a time. They handle exceptions the same way but with different methods of the CurrencyExchange class.

Below is an example of how to find multiple exchange rates:

Create function for arbitrary exchanges

This is the final exchange type. It allows users to state a base amount for an exchange.

The function below allows users to perform arbitrary exchange:

...
async def arbitrary_exchange(update: Update, context: ContextTypes.DEFAULT_TYPE):
   """ Exchange Currencies """
   arguments = "".join(context.args)
   split_arguments = arguments.split("@")

   try:
       base_currency = split_arguments[0].split("/")[0]
       target_currency = split_arguments[0].split("/")[1]
       base_amount = float(split_arguments[1])

   except IndexError:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text=f"Please enter values in the correct format"
       )

   except ValueError:
       await context.bot.send_message(
           chat_id=update.effective_chat.id,
           text=f"Please enter a valid number"
       )
   else:
       if currency_exchange.is_valid_currency(base_currency) and currency_exchange.is_valid_currency(target_currency):
           params = {
               "base": base_currency,
               "target": target_currency,
               "base_amount": base_amount
           }

           response = currency_exchange.single_exchange(params=params)
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text=f"<b>Base Currency:</b> {base_currency}\n"
                    f"<b>Target Currency:</b> {target_currency}\n"
                    f"<b>Exchange Rate:</b> {response['exchange_rate']}\n\n"
                    f"<i>This means that {response['base_amount']} {base_currency} is equal to "
                    f"{response['converted_amount']} {target_currency}</i>",
               parse_mode=telegram.constants.ParseMode.HTML
           )
       else:
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text=f"Error occurred! Ensure this bot supports the currencies you entered."
           )
...

The code above handles two exceptions. The first one is an IndexError which may occur if the user did not enter two currency codes split by a slash (/), and the other which handles a ValueError if the base_amount is not a valid number.

If there are no errors, the currency codes are validated to ensure they are acceptable by the API.

Below is an image that shows how a user can perform an arbitrary exchange:

Create and register all handlers

Congratulations on getting this far. The next step is to add each function to a handler and test the bot.

The code below shows you how to achieve this:

...
# The "main block"
if __name__ == "__main__":

   # direct messages handler
   message_handler = MessageHandler(filters.TEXT & (~filters.COMMAND), 
   direct_messages)

   base_currency_handler = CommandHandler('baseCurrency', 
   record_base_currency)
   target_currency_handler = CommandHandler('targetCurrencies', 
   record_target_currencies)

   exchange_handlers = [CommandHandler('singleExchange', 
                              single_exchange_rate),
                        CommandHandler("multipleExchange", 
                              multiple_exchange_rate),
                        CommandHandler("exchangeRate", 
                              arbitrary_exchange)]

   # Option list handlers
   callback_handlers = [CallbackQueryHandler(complete_registration, 
                          'yes'),
                       CallbackQueryHandler(complete_registration, 
                          'no')]

   # Add handlers to the bot
   application.add_handler(message_handler)
   application.add_handler(base_currency_handler)
   application.add_handler(target_currency_handler)
   application.add_handlers(callback_handlers)
   application.add_handlers(exchange_handlers)
   ...

Each function is added to a handler. The CallbackQueryHandler() is used to handle the select options created earlier in this tutorial.

Run the bot to test the progress so far. The bot should respond to all your messages and queries.

Protect the bot from unauthorized access.

Currently, the bot is accessible by anyone, both registered and unregistered users. This is the final defect of the bot.

If an unregistered user tries to enter a command in the bot, the bot should respond by telling them to register first.

Python decorators to the rescue

Python decorators are wrapper functions that accept other functions or classes as arguments. They are useful for validations in web apps.

For example, if a condition is satisfied, the wrapped function is returned and executed. Else, a warning message is sent or any other action performed.

For this tutorial, two decorators will be created. They are as follows:

1. A decorator for new users:
This decorator protects a function and makes it accessible by new users only. This is the code below:

def for_new_users(f):
   @wraps(f)
   async def wrapper_function(update: Update, context: ContextTypes.DEFAULT_TYPE):
       # Get a single user by chat_id
       user = db.query(User).filter_by(chat_id=update.effective_chat.id).first()

       # Checks if user exists
       if user:
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text="This endpoint is for new and unregistered users."
           )
       else:
           await f(update, context)
   return wrapper_function

In this decorator, the code checks a user's chat_id against the database. If the chat_id exists, the user is sent a warning message and denied access to the function. If otherwise, the user is allowed to continue with his/her registration.

2. A decorator for registered users:
This decorator protects a function and makes it accessible by registered users only. This is the code below:

def for_registered_users(f):
   @wraps(f)
   async def wrapper_function(update: Update, context: ContextTypes.DEFAULT_TYPE):
       # Get a single user by chat_id
       user = db.query(User).filter_by(chat_id=update.effective_chat.id).first()

       # Checks if user exists
       if not user:
           await context.bot.send_message(
               chat_id=update.effective_chat.id,
               text="This endpoint is for registered users. Kindly register to use this function"
           )
       else:
           await f(update, context)

   return wrapper_function

In this decorator, the code checks a user's chat_id against the database. If the chat_id exists, the user is allowed to continue with the bot. If otherwise, the user is sent a warning and instructed to complete his/her registration to access the function.

This way, registered users do not have to recreate a profile with the same account again.

Add the decorators to each function

Protect each function by adding the decorators as below:

@for_new_users
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
# Rest of the code

Assign a suitable decorator for each function. Check the full code on GitHub to see how the decorators are added to each function.

Set up daily updates

The final feature of the bot is to send personalized daily updates to users who opt-in for daily updates.

The job_queue package of the PTB library is used to set up cron jobs in Telegram bots.

Below is a function named daily_updates() that sends the personalized updates:

async def daily_updates(context: ContextTypes.DEFAULT_TYPE):
   all_users = db.User.all()

   # List of users who opt-in for daily updates
   will_receive_updates = [user for user in all_users if user.receive_updates is True]

   context.bot_data['cached_rates'] = {}

   # Function that sends updates
   async def send_update(user):
       base_currency = user.base_currency.upper()
       params = {
           "base": base_currency
       }
       chat_id = user.chat_id
       currency_pairs = user.currency_pairs.split(",")
       response = ""

       # Checks if an updates exists in the context dictionary
       try:
           cached_response = context.bot_data['cached_rates'][base_currency]
       except KeyError:
           response = currency_exchange.multiple_exchange(params)
       else:
           response = cached_response

       update_message = f"<b>Latest update on exchange rates relative to {base_currency}</b>\n" \
                        f"This means that 1 {base_currency} is equal to the following in different currencies:\n\n" \
                        f""
       for currency in currency_pairs:
           exchange_rate = response['exchange_rates'][currency.upper()]
           update_message += f"<b>{currency}</b>: {exchange_rate}\n"

       context.bot_data['recent_exchange_rates'][base_currency] = response
       await context.bot.send_message(
           chat_id=chat_id,
           text=update_message,
           parse_mode=telegram.constants.ParseMode.HTML
       )
   for user in will_receive_updates:
       await send_update(user)
       time.sleep(2)

   # Clears cached updates
   context.bot_data.clear()

In the function above, users who want daily updates are separated from others and added to a list.

Within this function, there is another asynchronous function that queries the API based on each user’s base and target currencies.

Each successful query is temporarily stored(cached) in the context dictionary of the bot. This is useful in situations where users might have similar base currency.

Instead of sending a request to the API every time, you can easily access it from within the bot and render results to users.

For example — John and Janet both have the same base currency which is USD. If John receives his update first, instead of sending a new request to the API for Janet’s update, you can easily use John’s own which has been saved to memory since they both have the same base currency.

If the next user has a different base currency, a new request is sent to the API and the result is also saved to memory in case there’s another user with the same base currency.

Finally, the cached data is cleared after all updates have been sent.

Caching API responses are not accepted by all APIs. In fact, it is considered a crime for some. In the case of the Exchange API, cached responses are not useful after a long time. This is because exchange rates fluctuate and change periodically. Therefore, using cached results would mean that your bot will not provide accurate exchange rates. It is only useful for situations like this where you have to send updates to users at once.

Create a cron job and register the updates function to the application by following the steps below:

Import the datetime module.
Add the code below in the “main block".

...
# The "main block"
if __name__ == "__main__":
   ...

   time_format = '%H:%M'
   reminder_time_string = '21:13'
   daily_job = application.job_queue
   datetime_obj = datetime.strptime(reminder_time_string, time_format)
   daily_job.run_daily(daily_updates, time=datetime_obj.time(), 
   days=tuple(range(7)))

   ...

In the code above, a daily cron job is created with the application.job_queue instance.

It is automatically set at UTC timing and it runs based on the specified time of the reminder_time_string.

It uses the Hours:Minutes(e.g 05:00) time format.

Conclusion: Next steps

The bot is up and running and delivers real time exchange rates to users. I'm sure you enjoyed building this project.

You learned how to apply some python concepts that help you write a clear and organized code.

What Next?

What's the joy of building something this beautiful without it being used by people?

That's why I’ve decided to create a new tutorial that will show you how to add a live postgresql database to the bot and host it live for others to use.

Follow me on LinkedIn to be the first to know when the new tutorial is out.

Telegram bots have a wide range of possibilities. This article explores the different kind of Telegram bots you can build to automate manual workflows.

Frequently asked questions (FAQs)

How can I host the Telegram bot for free?

Yes. There are free hosting services where you can host your Telegram bot. However, this particular bot requires a persistent memory and state persistence. It also runs and stores cron-jobs on them, hence you will need a more sophisticated solution.

A new article on how to solve this will be ready soon.

Can I host this Telegram bot on Google Cloud functions?

No. Google Cloud functions is suitable for hosting applications that does not require persistence or are stateless. They are only triggered when an action or event occurs in an application.

Which other Python libraries can be used to build a Telegram bot?

There are numerous Python libraries that can be used to build telegram bots. Here is a list of top 10 Python libraries for developing Telegram bots

How to handle media uploads in Django

Edun Rilwan — Sun, 12 May 2024 21:47:37 +0000

It is a common feature in most web apps to prompt users to upload files or documents. These files include image files (.jpeg, .jpg, .png) or other document files like PDFs, audio files (.mp3), etc.

Django, a very popular and powerful web framework in Python provides built-in methods and utilities that enables seamless upload and storage of files in web applications.

In Django, there are 3 ways to accept media uploads from users. They include the following:

Django ModelForms
Django Forms
Pure HTML forms

In this tutorial, you will learn how to handle media uploads with Django ModelForms using a local storage. Django's ModelForm provides a convenient and faster way to create forms in Django. They are also very customizable.

By the end of this tutorial, you would have learned the following:

How to receive media files via a ModelForm
How to handle and save the received file object
How to display saved image files on a web page
How to make saved files available for download by users.

Project requirements

Python: You need a Python interpreter installed on your computer. Preferably python>=3.8
Django: The latest version of Django is required.

Create a new virtual environment using the virtualenv package in Python:

virtualenv env

Use the command below to activate the virtual environment:

Windows:

env\Scripts\activate

Linux/macOS:

env/bin/activate

Install Django in the new virtual environment:

pip install Django

Note: To confirm your virtual environment (VE) is activated, check to see the name of your VE in a bracket like the one below:

(env) >>>

Getting started with Django file upload

You need to create a new Django project and app to learn how Django handles media uploads.

Create a Django project

Follow the steps below to create a Django project:

Open your terminal(check that your VE is activated).
Run the command below to create a Django project
```
django-admin startproject my_project
```
Enter the command below to move into the new my_project folder
```
cd my_project
```

Next step is to create an app.

Create a Django app

Run the command below in the terminal to create an app named
file_upload
```
python manage.py startapp file_upload
```
Open the settings.py file in your project folder and add the app to
the INSTALLED_APPS list as seen below:
```
#my_project/settings.py

INSTALLED_APPS = [
   ...
   "file_upload"
]
```

Django MEDIA ROOT and MEDIA URL

MEDIA_ROOT and MEDIA_URL variables are crucial in handling media uploads in a local filesystem storage. They provide a way of accessing and storing saved files in a Django app.

Django MEDIA ROOT

MEDIA ROOT refers to the root folder where all uploaded files are stored in a Django web app. It refers to the folder where all files can be accessed from.

How to set up a MEDIA ROOT

To set up a MEDIA ROOT, do the following:

Create a new folder named uploads in your project folder


#file_arrangement
my_project
   \__ my_project
   \__ file_upload
   \__ uploads

Open settings.py file and include the following line of code in it:
```
MEDIA_ROOT = BASE_DIR / "uploads"
```

This setting instructs Django to save uploaded files to the uploads folder within your project, that is BASE_DIR.

BASE_DIR is a variable automatically set by Django. It contains the file path to your current project, which is also known as the base directory.

Django MEDIA URL

MEDIA URL refers to the root URL that renders user-uploaded files present in the MEDIA ROOT of a web app.

For example, if you uploaded an image file titled example.jpg, it is rendered on the web via a url like the one below:

https://mysite/[MEDIA_URL]/[MEDIA_ROOT]/images/example.jpg

The URL above is analyzed as follows:

mysite is the domain name of your website.
media_url is the base/root url for uploaded media.
media_root is the root folder for uploaded media.
images is another folder inside the MEDIA ROOT that stores image files only
example.jpg is the file name.

How to set up a MEDIA URL

Open your project's settings.py file and add the code below:

   MEDIA_URL = "files/"

Open the urls.py file in your project folder

Add the following import statements:

from django.conf import settings
from django.conf.urls.static import static

Write the following code below the urlpatterns list in the urls.py
file:

urlpatterns += static(settings.MEDIA_URL, 
    document_root=settings.MEDIA_ROOT)

In the steps above, a MEDIA URL, named files is created. This root url for media uploads is finally added to the list of URLs.

Create a Database Model

The next step is to create a database model named Uploads. This model will have three field types which includes: A Charfield, FileField and an ImageField. Follow the steps below to create the Uploads model:

a. Go to the models.py file in your app
b. Create a simple database model titled Uploads

from django.db import models

# Create your models here.
class Uploads(models.Model):
   caption = models.CharField(unique=False, null=False, blank=False, max_length=20, default="An image")
   file_field = models.FileField(upload_to="files", null=False, blank=False)
   image_field = models.ImageField(upload_to="images", null=False, blank=False)

The functions of each field are listed below:

CharField stores textual data.
FileField stores files such as PDFs, docx, etc.
ImagField stores image files.

The FileField and ImageField have an upload_to argument. This refers to a new folder inside your project's MEDIA ROOT where the content of each file field will be stored. It is created automatically when a file is uploaded to each field.

Run migrations for the database

Run database migrations via the steps below:

a. Open the terminal and run this command

python manage.py makemigrations

b. Run the command below to add the migrations to a file

python manage.py migrate

Migrations help to track changes made to the database.

Build a ModelForm

Follow the steps below to build a ModelForm:

a. Create a forms.py file in your app folder

my_project
   \___ file_upload
          \___ ...
          \___ forms.py

b. Add the code below to the file:

from django import forms
from .models import Uploads

class FileUploadForm(forms.ModelForm):
   class Meta:
       model = Uploads
       fields = "__all__"

The code above creates a ModelFormbased on the structure of the Uploads model. The __all__ method means that the form should contain all the fields in the database model.

Create a view for media uploads

Follow the steps below to create a view function:

a. Open the views.py file
b. Add the code below

from django.shortcuts import render, redirect
from .forms import FileUploadForm
from .models import Uploads


# Create your views here.

def handle_upload(request):
   form = FileUploadForm()
   if request.method == "POST":
       form = FileUploadForm(request.POST, request.FILES)
       if form.is_valid():
           form.save()

   return render(request, "form.html", context={"form": form})

The view function renders the ModelForm through a form.html file that will be created in the next step.

This view also accepts POST requests from the ModelForm when the user submits their uploads. It verifies that there are no form errors before saving the user input.

It is necessary to include the request.FILES and request.POSTdictionary in the form class for each POST request.

POST requests are usually sent with a requests.POST dictionary. When files are involved, a request.FILES dictionary is added.

Uploaded files are stored temporarily in a request.FILES dictionary. Each key in this dictionary holds the data of a particular file field in the form submitted.

For example, if you created a form with a FileField named "images", you can access the file data in your views function via the code below:

request.FILES['images']

Create the homepage file

You need to create an HTML file named form.html that'll render the form. Follow the steps below to do create a web page:

a. Create a new folder named templates in your project

my_project
   \___ my_project
   \___ ...
   \___ templates
   \___ ...

b. Create a new HTML file named form.html inside this folder
c. Add the code below inside this file

<head>
   <meta charset="UTF-8">
   <title>Forms practise</title>
</head>


<body>

<form method="post" action="" enctype="multipart/form-data">
   {% csrf_token %}

   {{ form.as_p }}
   <input type="submit" name="submit">

</form>

</body>

The HTML code above displays the form to the user through form.as_p, while the {% csrf_token %} enables secured transfer of form data

The enctype="multipart/form-data" variable enables the form to send file data.

Finally, you need to register the templates folder with Django so it can access it.

To do this, open the settings.py file in your project folder and add the code below to the TEMPLATESlist in this file:

TEMPLATES = [
    {
        '...',
        'DIRS': [os.path.join(BASE_DIR, 'templates')],
        '...'
    }
]

Configure app urls.

The next step is to bind the view function to a url. Follow the steps below to do this:

a. Open the urls.py file in your app folder

my_project
   \___ file_upload
      \___ ...
      \___ urls.py
      \___ ...

b. Add the code below to this file

from django.urls import path
from file_upload import views

urlpatterns = [path("", views.handle_upload, name="home")]

c. Open the urls.py file in your project folder

my_project
  \___ my_project
     \___ ...
     \___ urls.py
     \___ ...

d. Register your app URLs to the urlpatterns list in your project.

from django.contrib import admin
from django.urls import path, include
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    "...",
    path("", include("file_upload.urls")),
]

Test the app

a. Run the command below in your terminal

python manage.py runserver

b. Click on the link to open the web page
c. Click on the _Choose file _button to upload your files.

c. Enter a caption of your choice.
d. Submit the form.
e. Proceed to the uploadfolder, you would see two new folders named filesand images.

In the files folder, you would see the document you uploaded.
In the images folder, you would see the image file you uploaded.

Display user uploads

In most cases, users would need access to their files. You can display media uploads to users using a simple .url attribute. The steps below show you how to display uploaded files to users:

a. Open the views.py file
b. Update the view function to contain the Uploads model and pass it to the render function.

from django.shortcuts import render, redirect
from .forms import FileUploadForm
from .models import Uploads

# Create your views here.
def handle_upload(request):
   form = FileUploadForm()
   uploads = Uploads.objects.all()
   if request.method == "POST":
       form = FileUploadForm(request.POST, request.FILES)
       if form.is_valid():
           form.save()
           return redirect("home")

   return render(request, "form.html", context={"form": form, "uploads": uploads})

c. Proceed to the form.html file
d. Add this code below the form in the HTML file

{% for media in uploads %}
{% if media %}

<div style="margin: 20px 0px;">

   <img src="{{ media.image_field.url }}" height="200px;" width="200px;">
   <p>{{ media.caption }}</p>
   <p>Download your file <a href="{{ media.file_field.url }}">here</a></p>

</div>

{% endif %}
{% endfor %}

e. Wait for the server to reload
f. Open the browser and refresh the web page

This process simply queries all records in the Uploads model, adds it to the context dictionary so it can be accessed and used in the HTML file.

The image you uploaded will be displayed on the web page and your document will be available for download. Here is an example below:

Conclusion

Leveraging Django's ModelForms for file uploads simplifies the process of handling user-submitted files. Whether it's for pictures, documents or any other type of file, ModelForms provides an efficient and structured way to manage file uploads in Django.

Frequently asked questions (FAQs)

What type of media files can be uploaded in Django?

You can upload files of different sizes and formats in Django. However, if you are using a local file-storage, you will get to a point where the memory gets full and you will need to use a cloud service like AWS, Google clouds, etc.

An overloaded memory will affect site performance.

How can I secure media uploads in Django?

There are different security measures you can apply to media uploads in Django. They include:

Verifying the file formats before saving them. That is, by checking the file extensions, such as .png, .jpg, .pdf, etc. to be sure they are safe
Sometimes, reading file metadata before saving is also important. However, you may need to use third-party Python libraries to like Pillow to implement this.

How to handle media uploads in a production environment?

It is not advisable to use a local file storage in a production environment. This is because such implementation may have security implications on stored files.

Using cloud services enhance application performance and provide more flexibility and security to uploaded files.

Can I resize or manipulate uploaded images in Django?

Yes, you can.

Before saving an uploaded file, you can get the file object from the request.FILES dictionary and use it directly with a file manipulation library like Pillow, OpenCV, etc. in Python.

After editing the image, you can then save it to a file of your choice.

How does the Django Filesystem work?

When a user uploads a file in Django, the Django filesystem has two handlers that handles file uploads. For small files, they are saved to memory using the (handler) handler while the (handler) handler handles large files by saving them to a temporary file.

What happens when I delete saved files in Django?

Deleted files are immediately removed from the MEDIA ROOT of your app. Therefore, trying to access a deleted file through the .url attribute will throw an error.

Forem: Edun Rilwan

A Goldmine for documentation leads/Technical writers

How to Migrate Technical Documentation: Tools, Checklist, and Tips

How to Migrate Technical Documentation: Tools, Checklist, and Tips

What is documentation migration

When to consider migrating your documentation

Popular documentation platforms & SSGs

Steps to follow when performing a documentation migration

Tips for migration

Conclusion

Docs-as-code in action: Documenting a Python library.

What is Docs-as-code?

Project Overview

Project requirements

Setup a Mintlify documentation

Add the documentation to your project

Preview documentation locally

Writing the documentation

Edit documentation settings

How to add content

Documentation writing tips

Push the project to Github

Deploy the documentation

Updating the Project

Conclusion

FAQs

How to build and deploy a Python library

Project Overview

The Python Library

Project requirements

Tools and Packages

Create a new project.

Setup project resources

Build the API wrapper

Wrap the /live endpoint

Wrap the /historical endpoint

Wrap the /convert endpoint

Test the API wrapper

Deploy the project

Setup deployment requirements

Deploy the library

Project maintenance

Installation and usage

Conclusion

Wrap and Render Multiline Text on Images Using Python's Pillow Library

Requirements

Create a new project

Prepare base image

Annotate the image

Enable automatic text wrapping

Set up a dynamic box height

Add text padding

Add a pointer

Conclusion

How to view API request examples in a ReadMe documentation.

The Problem

The solution

Conclusion

Building SaaS Faster with Ercas for SaaS: A Template for Indie Hackers

Introduction

Key features

Project requirements

How to install EFS

Understanding the project files

How to run the EFS plug-in locally

Editing and customization

Conclusion

How to build a fully-fledged telegram bot in Python

Introduction

Requirements

Create a Telegram bot

Create an Abstract API account

Get your Abstract API key

Build the Telegram bot

Initial application setup

Create the start command

Register the start command

Create a database connection

Create a database model

Create the database file