DEV Community: Rekan Othman

Keep Module Documentation Next to the Code

Rekan Othman — Sat, 01 Aug 2026 10:06:53 +0000

Sometimes code looks wrong for a good reason.

You open an order module and find this:

class Order:
    shipping_street = ...
    shipping_city = ...
    shipping_postal_code = ...
    shipping_country = ...

Why store the customer's address again?

The customer already has an address. It would seem cleaner to store a reference instead.

But there is a problem.

Customers can change their address. If the order points to the customer record, then the day a customer moves, every past order starts showing the new address. A delivery dispute from last year now points to a place the package was never sent.

An old order has to keep the address that was used when the order was placed.

So the duplicated address is not a mistake. It is part of the design.

The problem is that the reason is not obvious from the code.

The Simple Solution

Keep a small README.md inside the module:

orders/
  docs/
    README.md
  models/
  services/

Not in a wiki, and not in a shared document somewhere else. Inside the module, so the person reading the code finds it without looking for it, and so it travels with the code when the code changes.

Then document the decision:

## Key Decision

Orders store a copy of the shipping address.

Customers can change their address later,
but old orders must keep the address used
when the order was placed.

Do not replace these fields with a
customer address reference.

Now the next developer does not have to guess.

The code shows what the system does. The markdown file explains why.

Keep It Small

You do not need to document every function, model field, or file. If the code already answers it, leave it out.

Only write down the things that are not obvious from the code:

important decisions
business rules
unusual behavior
things that look wrong but are intentional

A few lines are often enough.

Key Takeaway

A module isn't finished when it works. It's finished when someone else can change it safely.

Good code explains how a system works. A small markdown file can explain why it works that way.

Keep that explanation next to the code, while the decision is still fresh.

It may save the next developer from "fixing" something that was never broken.

The Same Idea in a Working Project

A small Django REST Framework and PostgreSQL project built around this exact decision. Two modules, each with its own docs/README.md, and a test that fails if someone removes the duplicated address fields:

https://github.com/rekanothman/docs-next-to-code

Place an order, change that customer's address, then read the order back.

A Reliable Way to Prevent Duplicate Database Records

Rekan Othman — Sat, 01 Aug 2026 10:03:45 +0000

Every transactional system must answer one question:

If the same request arrives twice, will the database contain one record or two?

Duplicate requests happen for many reasons — and a double-click is only the most visible one:

Double-clicks on a save button
Browser retries after a timeout
Network interruptions and reconnects
Reverse proxy or load balancer retries
Mobile clients resending after losing signal
Frontend bugs firing a request twice
API consumers retrying failed calls
Webhook providers resending events

You cannot prevent duplicate requests. You can only prevent duplicate records. The answer is idempotency, enforced by the database.

Throughout this article, keep one distinction in mind: Django handles validation. PostgreSQL guarantees correctness. We'll implement the pattern in an invoice module as our example, but it applies to any create endpoint.

The Problem

A user saves an invoice. The request is slow, the request is retried — by the user, the browser, or the network — and now two identical invoices exist. Reports, inventory, and accounting are all wrong. The same failure can hit orders, payments, registrations, or any other module that creates data.

Why Client-Side Prevention Isn't Enough

Disabling the save button while a request is in flight is good UX and stops most accidental double-clicks:

<button :disabled="saving" @click="save">Save</button>

But it does nothing against network retries, refreshes, proxies, or other API consumers. The frontend can reduce duplicates; it can never guarantee anything.

What the frontend can usefully do is give each operation an identity. Generate an idempotency key when the operation begins — not when the request is sent — and reuse it for every attempt:

data() {
  return {
    invoice: {},
    idempotencyKey: crypto.randomUUID(), // once per operation
  };
},
methods: {
  async save() {
    await axios.post('/api/invoices/', this.invoice, {
      headers: { 'X-Idempotency-Token': this.idempotencyKey },
    });
  },
  newInvoice() {
    this.invoice = {};
    this.idempotencyKey = crypto.randomUUID(); // reset only here
  },
},

One operation, one key. If you generate the key per request (for example, in a global Axios interceptor), every retry looks like a new operation and the server cannot deduplicate it.

Why Checking First Doesn't Work

The intuitive backend approach is to check before inserting:

if not Invoice.objects.filter(idempotency_key=token).exists():
    Invoice.objects.create(idempotency_key=token, ...)

Under concurrency, this fails:

Request A arrives
    ↓
exists() → false
                        Request B arrives
                            ↓
                        exists() → false
A inserts row
                        B inserts row   ← duplicate

Both requests pass the check before either inserts. This "check-then-act" race applies equally to cache-based deduplication (cache.get() then cache.set()). No application-level check can fix this, because the check and the insert are two separate steps — and another request can run between them.

A note on get_or_create(): many Django developers reach for it here, but it doesn't replace idempotency. Internally it's still a lookup followed by an insert, and it only helps when the lookup fields already represent business uniqueness. An idempotency key is different: it identifies a single client operation, regardless of the record's contents.

Let PostgreSQL Guarantee Uniqueness

The fix is to move the guarantee into the database:

class Invoice(models.Model):
    idempotency_key = models.UUIDField(unique=True, db_index=True)
    # ... your fields

Why does this work when application checks don't? Because PostgreSQL performs the uniqueness check and the insert as a single atomic operation inside the database engine. Two concurrent transactions cannot both insert the same unique value — one succeeds, the other fails with an IntegrityError. There is no gap between the check and the insert, so a race condition is impossible.

So instead of treating IntegrityError as a failure, we treat it as a signal that the work is already done:

from django.db import IntegrityError, transaction

def create(self, request):
    token = request.headers.get("X-Idempotency-Token")
    if not token:
        return Response({"detail": "Idempotency token required."}, status=400)

    serializer = InvoiceSerializer(data=request.data)
    serializer.is_valid(raise_exception=True)

    try:
        with transaction.atomic():
            invoice = serializer.save(idempotency_key=token)
    except IntegrityError:
        invoice = Invoice.objects.get(idempotency_key=token)
        return Response(InvoiceSerializer(invoice).data, status=200)

    return Response(InvoiceSerializer(invoice).data, status=201)

First request: 201 Created. Any replay: 200 OK with the same record. Django validated the request; PostgreSQL guaranteed the correctness.

Add Business Constraints

One layer of protection is good; two are better. Most records also have a natural uniqueness rule of their own. Enforce it as a second constraint:

class Meta:
    constraints = [
        models.UniqueConstraint(
            fields=["terminal_id", "number"],
            name="unique_invoice_per_terminal",
        )
    ]

Even if a future bug bypasses the idempotency key, PostgreSQL still refuses the duplicate. Constraints cost nothing and protect you from bugs you haven't written yet.

The Reusable Architecture

The complete flow, reusable in any module:

Client
    ↓  generate one idempotency key per operation
Django
    ↓  validate the request
PostgreSQL
    ↓  unique constraint enforces exactly-once insert
IntegrityError
    ↓  caught by Django
Return the existing resource (200 OK)

Every create endpoint in your system can follow this exact shape.

When Should You Use This?

Use idempotency for anything where a duplicate causes damage:

Invoices, orders, and purchase orders
Payments and money transfers
Inventory movements and shipments
Ticket creation and registrations

Skip it for operations that are naturally safe to repeat:

Search endpoints
Reports and analytics
Any read-only API

Performance

A unique index check is a single, extremely fast lookup — it takes microseconds. The constraint adds no meaningful overhead to inserts, and PostgreSQL handles this pattern at high write volumes without queues, distributed locks, or any special infrastructure. For the vast majority of applications, performance is simply not a concern here.

Key Takeaway

A transactional system should never rely on timing, client behavior, or network conditions to maintain data integrity — those are unpredictable. The database is the only component capable of guaranteeing uniqueness under concurrency. Generate one idempotency key per operation, enforce it with a PostgreSQL unique constraint, and catch IntegrityError to return the existing record. Build your API around that guarantee, and duplicate record bugs disappear permanently.

Upload Files to Dropbox using Python 🐍

Rekan Othman — Thu, 14 Mar 2024 09:26:14 +0000

Do you spend time manually uploading files to Dropbox? Take control with Python! In this article, I'll share my Python program that simplifies file uploads to Dropbox.

Prerequisites

Before we dive into the Python script, make sure you have the following:

A Dropbox account
Python installed on your machine: Download and install Python from python.org.

Create an App on Dropbox

To create an app on Dropbox, go to Dropbox Developer Apps.

After creating an app you have an App key, App secret please keep it secret, and generate Access Token” by click on Generate button.

After generating Access Token now go to permissions section and set the required permissions.

Setting Up the Project

To get started, create a new Python script and install the necessary packages. Open your terminal or command prompt and run the following commands:

pip install dropbox
pip install requests
pip install configparser
pip install pybase64
pip install jsonlib

Obtaining Access Code

Open your preferred text editor and create a new Python file. You can name it get_access_code.py. Now copy the following code into your Python script file

import webbrowser

APP_KEY = '<APP_KEY>'
url = f'https://www.dropbox.com/oauth2/authorize?client_id={APP_KEY}&' \
      f'response_type=code&token_access_type=offline'

webbrowser.open(url)

Replace APP_KEY with your Dropbox App key. This code will open a browser window prompting you to log in to your Dropbox account and authorize access for your app. After authorization, Dropbox will redirect you to a URL containing the access code.

Run the Script: Save the Python script and execute it by running the following command in your terminal or command prompt:

python get_access_code.py

Authorize Dropbox Access: Follow the prompts in your browser to log in to your Dropbox account and authorize access for your app. Once authorized, you will be redirected to a page displaying the access code.

Copy the Access Code: Copy the access code from the browser window. We'll use this access code in our Python script to authenticate with Dropbox's API.

Obtaining Refresh Token

Open your preferred text editor and create a new Python file. You can name it get_refresh_token.py. Copy the following code into your Python script file:

import base64
import requests
import json

APP_KEY = '<APP_KEY>'
APP_SECRET = '<APP_SECRET>'
ACCESS_CODE_GENERATED = '<ACCESS_CODE_GENERATED>'

BASIC_AUTH = base64.b64encode(f'{APP_KEY}:{APP_SECRET}'.encode())

headers = {
    'Authorization': f"Basic {BASIC_AUTH}",
    'Content-Type': 'application/x-www-form-urlencoded',
}

data = f'code={ACCESS_CODE_GENERATED}&grant_type=authorization_code'

response = requests.post('https://api.dropboxapi.com/oauth2/token',
                         data=data,
                         auth=(APP_KEY, APP_SECRET))
print(json.dumps(json.loads(response.text), indent=2))

Replace APP_KEY, APP_SECRET, and ACCESS_CODE_GENERATED with your Dropbox app key, app secret, and the access code obtained in the previous step.

Run the Script: Save the Python script and execute it by running the following command in your terminal or command prompt:

python get_refresh_token.py

the output is

With the refresh token obtained, we can now proceed to integrate it into our Python script for uploading files to Dropbox.

Creating Credentials Configuration File

To securely store your Dropbox app's credentials and tokens, we'll create a configuration file named credentials.ini.

Open your preferred text editor and create a new file named credentials.ini. Copy the following content into the credentials.ini file:

[Authentication]
access_token = <ACCESS_TOKEN>
app_key = <APP_KEY>
app_secret = <APP_SECRET>
refresh_token = <REFRESH_TOKEN>

Replace ACCESS_TOKEN, APP_KEY, APP_SECRET, and REFRESH_TOKEN with the corresponding values:

ACCESS_TOKEN: Your Dropbox app's generated access token.
APP_KEY: Your Dropbox app key.
APP_SECRET: Your Dropbox app secret.
REFRESH_TOKEN: The refresh token obtained from the get_refresh_token.py script.

Save the credentials.ini file in the same directory as your Python scripts.

Writing the Python Script

Now, let's create the Python script to upload a file to Dropbox. We'll use the Dropbox API and the dropbox Python library for seamless integration.

import os
import dropbox
import requests
import configparser

class DropboxUploader:
    def __init__(self):
        # Configuration parameters
        self.source_directory = ""
        self.local_file_path = 'file.txt'
        self.credentials_directory = "credentials.ini"
        self.dropbox_directory = "/file_backups"

        # Initialize Dropbox API with access token
        self.access_token = self.read_credentials_value("Authentication", "access_token")
        self.dbx = dropbox.Dropbox(self.access_token)

    def read_credentials_value(self, section, key):
        # Read a value from the credentials file
        config = configparser.ConfigParser()
        config.read(self.credentials_directory)

        try:
            return config.get(section, key)
        except (configparser.NoSectionError, configparser.NoOptionError) as e:
            print(f"read_credentials_value function: Error reading config value: {e}")
            return None

    def update_credentials_key_value(self, section, key, value):
        # Update a key-value pair in the credentials file
        config = configparser.ConfigParser()
        config.read(self.credentials_directory)
        config.set(section, key, value)

        with open(self.credentials_directory, 'w') as config_file:
            config.write(config_file)
            print(f"Key '{key}' value updated successfully in section '{section}'")

    def generate_new_access_token(self, app_key, app_secret, refresh_token):
        # Generate a new access token using the provided credentials
        url = "https://api.dropbox.com/oauth2/token"
        headers = {"Content-Type": "application/x-www-form-urlencoded"}
        data = {
            "grant_type": "refresh_token",
            "refresh_token": refresh_token,
            "client_id": app_key,
            "client_secret": app_secret,
        }

        response = requests.post(url, headers=headers, data=data)

        if response.status_code == 200:
            return response.json().get("access_token")
        else:
            print("generate_new_access_token function: Failed to get a new access token.")
            print(f"generate_new_access_token function: Status code: {response.status_code}")
            print(f"generate_new_access_token function: Response: {response.text}")
            return None

    def check_token_validity(self):
        # Check if the existing token is still valid
        try: 
            self.dbx.files_list_folder('')
            print("Token is valid")
        except dropbox.exceptions.AuthError:
            print("Token is expired, generating new access token ...")
            app_key = self.read_credentials_value("Authentication", "app_key")
            app_secret = self.read_credentials_value("Authentication", "app_secret")
            refresh_token = self.read_credentials_value("Authentication", "refresh_token")
            new_token = self.generate_new_access_token(app_key, app_secret, refresh_token)

            if new_token:
                self.update_credentials_key_value("Authentication", "access_token", new_token)
                self.access_token = new_token
                self.dbx = dropbox.Dropbox(self.access_token)
        except dropbox.exceptions.DropboxException as e:
            print("check_token_validity function: An error occurred while checking the token:", e)

    def upload_files(self):
        # Upload a file to Dropbox
        try:
            self.check_token_validity()
            file_name = os.path.basename(self.local_file_path)

            with open(self.local_file_path, "rb") as file:
                self.dbx.files_upload(file.read(), f"{self.dropbox_directory}/{file_name}", mode=dropbox.files.WriteMode("overwrite"))
                print(f"File '{file_name}' uploaded successfully to Dropbox.")

        except Exception as e:
            print("upload_files function: An error occurred:", e)

def main():
    # Main program flow
    print("Start uploading files ...")
    dropbox_uploader = DropboxUploader()
    dropbox_uploader.upload_files()
    print("End uploading files")

if __name__ == "__main__":
    main()

Now that your Python script is ready, you can run it to upload a file to your Dropbox account. Execute the following command in your terminal or command prompt:

python main.py

Conclusion

Congratulations! You've successfully created a Python script to upload files to Dropbox.

Feel free to customize the script further based on your specific requirements. You can add error handling, implement batch uploads, or integrate it into a larger project for a more comprehensive solution.

You can also clone the app from GitHub: python-dropbox-file-uploader