Improve documentation clarity, fix typos, and align project descriptions (#14)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: johnbrandborg

README.md

@@ -1,87 +1,95 @@
-# "Create, Read, Update, Delete"s
+# CRUDs
 
 [![PyPI - Version](https://img.shields.io/pypi/v/cruds)](https://pypi.org/project/cruds/)
 [![Supported Python Version](https://img.shields.io/pypi/pyversions/cruds?logo=python&logoColor=FFE873)](https://pypi.org/project/cruds/)
 [![Development](https://github.com/johnbrandborg/cruds/actions/workflows/development.yml/badge.svg)](https://github.com/johnbrandborg/cruds/actions/workflows/development.yml)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=johnbrandborg_cruds&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=johnbrandborg_cruds)
 [![Documentation Status](https://readthedocs.org/projects/cruds/badge/?version=latest)](https://cruds.readthedocs.io/en/latest/?badge=latest)
 
-**CRUDs** is a high level client library for APIs written in Python, and is ideal for back-end
-communication, automated data processing and interactive environments like Notebooks.
+**CRUDs** is a lightweight Python client for REST APIs — create, read, update,
+and delete with zero boilerplate.
 
 ```python
->>> import cruds
->>>
->>> catfact_ninja = cruds.Client("catfact.ninja")
->>>
->>> data = catfact_ninja.read("fact")
->>> type(date)  # Python built-in data types you can use instantly!
-<class 'dict'>
-```
+import cruds
 
-## Why CRUDs?
+api = cruds.Client("https://api.example.com", auth="your-token")
 
-When working with APIs, you have several options. Here's why CRUDs might be the right choice:
+# Create a resource
+user = api.create("users", data={"name": "Ada", "role": "engineer"})
 
-**vs. requests/httpx/urllib3:**
-- **Semantic API Design**: Think about what you're doing (create, read, update, delete) instead of HTTP methods
-- **Production-Ready**: Built-in retry logic, error handling, and logging without configuration
-- **Simplified Auth**: OAuth2, bearer tokens, and basic auth handled automatically
-- **Data-First**: Returns Python data structures directly instead of response objects
+# Read it back
+user = api.read(f"users/{user['id']}")
 
-**vs. SDKs for specific APIs:**
-- **Consistent Interface**: Same patterns across all APIs
-- **No Vendor Lock-in**: Switch between APIs without learning new patterns
-- **Lightweight**: No need for multiple heavy SDKs
-- **Customizable**: Full control while maintaining simplicity
+# Update it
+api.update(f"users/{user['id']}", data={"role": "lead"})
 
-**Perfect for:**
-- Data engineers working with multiple APIs
-- Backend developers building integrations
-- Data scientists in notebooks
-- DevOps teams automating API interactions
+# Delete it
+api.delete(f"users/{user['id']}")
+```
 
-Make Create, Read, Update and Delete operations quickly, easily, and safely. CRUDs
-aims to implement URLLib3's best practises while remaining as light as possible.
+No response objects to unpack. No manual JSON parsing. No boilerplate retry
+logic. Just your data.
 
-Features:
- * Authentication: Username & Password, Bearer Token and OAuth2
- * JSON Serialization/Deserialization
- * Request parameters and automatically URL encoded
- * Configurable timeouts (default 5 minutes)
- * Exceptions handling for bad status codes
- * Built-in retry logic with exponential backoff
- * SSL Certificate Verification
- * Logging for monitoring
- * Interfaces (SDK Creation)
+## Quickstart
 
-### Interfaces
+```bash
+pip install cruds
+```
 
-CRUDs provides pre-configured interfaces for popular APIs, making integration even easier:
+```python
+import cruds
 
-* **PlanHat** - Complete customer success platform interface with 20+ data models, bulk operations, and advanced analytics. [View Documentation](https://cruds.readthedocs.io/en/latest/interfaces.html#planhat)
+catfacts = cruds.Client("catfact.ninja")
+fact = catfacts.read("fact")
+print(fact["fact"])
+```
 
-### Installation
+## Why CRUDs over requests/httpx?
 
-To install a stable version use [PyPI](https://pypi.org/project/cruds/).
+| You get                    | Without writing          |
+|----------------------------|--------------------------|
+| Semantic CRUD methods      | HTTP method boilerplate  |
+| Automatic JSON SerDes      | `.json()` / `.raise_for_status()` calls |
+| Retry with backoff         | `HTTPAdapter` / `Retry` setup |
+| Bearer, Basic & OAuth2 auth| Manual header management |
+| SSL verification           | `certifi` wiring         |
 
-```bash
-$ pip install cruds
+```python
+# requests — 6 lines of ceremony
+import requests
+response = requests.get("https://api.example.com/users",
+                        headers={"Authorization": "Bearer token"})
+response.raise_for_status()
+users = response.json()
+
+# CRUDs — 2 lines of intent
+import cruds
+users = cruds.Client("api.example.com", auth="token").read("users")
 ```
 
-### Documentation
+## Features
+
+- **Authentication** — Bearer tokens, username/password, and OAuth2 (Client
+  Credentials, Resource Owner Password, Authorization Code with CSRF protection)
+- **JSON Serialization** — Send and receive Python dicts and lists directly
+- **Retries with backoff** — Configurable retry count, backoff factor, and
+  status codes (429, 500–504, etc.)
+- **Error handling** — Automatic exceptions for 4xx/5xx responses
+- **SSL verification** — Enabled by default via certifi
+- **Logging** — Built-in INFO/DEBUG logging for monitoring
+- **Interfaces** — Build SDKs with YAML configuration (ships with a full
+  [Planhat](https://cruds.readthedocs.io/en/latest/interfaces.html#planhat)
+  interface)
+
+## Documentation
 
-Whether you are an data engineer wanting to retrieve or load data, a developer
-writing software for the back-of-the-front-end, or someone wanting to contribute
-to the project, for more information about CRUDs please visit
-[Read the Docs](https://cruds.readthedocs.io).
+Full user guide, API reference, and examples at
+**[cruds.readthedocs.io](https://cruds.readthedocs.io)**.
 
 ## License
 
-CRUDs is released under the MIT License. See the bundled
-[LICENSE file](https://github.com/johnbrandborg/cruds/blob/main/LICENSE)
-for details.
+MIT — see [LICENSE](https://github.com/johnbrandborg/cruds/blob/main/LICENSE).
 
 ## Credits
 
-* [URLLib3 Team](https://github.com/urllib3)
+* [urllib3 Team](https://github.com/urllib3)

docs/changelog.rst

@@ -1,6 +1,29 @@
 Changelog
 =========
 
+Release 1.5.0 (February 20, 2026)
+----------------------------------
+
+Updates:
+ - Modernized project tooling: migrated from setup.cfg/setup.py to pyproject.toml
+   and adopted uv for dependency management.
+ - Aligned urllib3 usage with current best practices.
+ - Updated SonarQube scan action from v4 to v6.
+ - Minimum supported Python version is now 3.10.
+
+Release 1.4.2 (September 9, 2025)
+----------------------------------
+
+Fixes:
+ - Enhanced response handling in Planhat bulk upsert logic to skip non-dictionary
+   types.
+
+Release 1.4.1 (July 1, 2025)
+-----------------------------
+
+Fixes:
+ - Version bump to resolve PyPI version conflict with 1.4.0.
+
 Release 1.4.0 (June 30, 2025)
 ------------------------------
 

docs/development.rst

@@ -4,14 +4,14 @@ Development
 ===========
 
 At this time because the CRUDs code base is located on a repository not located
-under an Orgination, to contribute it is recommended that you create a fork of
+under an Organization, to contribute it is recommended that you create a fork of
 CRUDs and then `Create a PR <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
 from there.
 
 Setup
 -----
 
-It is highlight recommended to create a virtual environment of Python.  There are
+It is highly recommended to create a virtual environment of Python.  There are
 multiple ways to do this.  The standard way is using Pythons very own
 `venv <https://docs.python.org/3/library/venv.html>`_.
 

docs/examples.rst

@@ -1,13 +1,117 @@
 Examples
 ========
 
-Here you can find code snippets that show how easy it is to work with some platforms.
+Here you can find code snippets that show how easy it is to work with various
+platforms and public APIs.
+
+JSONPlaceholder (Try It Now)
+----------------------------
+
+`JSONPlaceholder <https://jsonplaceholder.typicode.com/>`_ is a free fake REST
+API — perfect for testing CRUDs without any API keys.
+
+.. code-block:: python
+
+    import cruds
+
+    api = cruds.Client("jsonplaceholder.typicode.com")
+
+    # Read all posts
+    posts = api.read("posts", params={"_limit": 5})
+    print(f"Got {len(posts)} posts")
+
+    # Create a new post
+    new_post = api.create("posts", data={
+        "title": "Hello from CRUDs",
+        "body": "This was easy.",
+        "userId": 1,
+    })
+    print(f"Created post #{new_post['id']}")
+
+    # Update the post
+    api.update(f"posts/{new_post['id']}", data={"title": "Updated title"})
+
+    # Delete the post
+    api.delete(f"posts/{new_post['id']}")
+
+GitHub API
+----------
+
+Read public repository data from the GitHub REST API.
+
+.. code-block:: python
+
+    import cruds
+
+    github = cruds.Client("api.github.com")
+
+    # Get repository info (no auth needed for public repos)
+    repo = github.read("repos/johnbrandborg/cruds")
+    print(f"{repo['full_name']} — {repo['stargazers_count']} stars")
+
+    # List recent commits
+    commits = github.read("repos/johnbrandborg/cruds/commits", params={"per_page": 5})
+    for commit in commits:
+        print(f"  {commit['sha'][:7]} {commit['commit']['message'].splitlines()[0]}")
+
+With a personal access token you can access private resources:
+
+.. code-block:: python
+
+    github = cruds.Client("api.github.com", auth="ghp_your_token_here")
+    user = github.read("user")
+    print(f"Authenticated as {user['login']}")
+
+Weather API
+-----------
+
+Fetch weather data from the free `Open-Meteo <https://open-meteo.com/>`_ API
+(no API key required).
+
+.. code-block:: python
+
+    import cruds
+
+    weather = cruds.Client("api.open-meteo.com")
+
+    forecast = weather.read("v1/forecast", params={
+        "latitude": -33.87,
+        "longitude": 151.21,
+        "current_weather": True,
+    })
+
+    current = forecast["current_weather"]
+    print(f"Sydney: {current['temperature']}°C, wind {current['windspeed']} km/h")
+
+Authenticated API with OAuth2
+-----------------------------
+
+For APIs that require OAuth2 Client Credentials (common in B2B integrations):
+
+.. code-block:: python
+
+    from cruds import Client
+    from cruds.auth import OAuth2
+
+    api = Client(
+        host="https://api.example.com",
+        auth=OAuth2(
+            url="https://api.example.com/oauth/token",
+            client_id="your-client-id",
+            client_secret="your-client-secret",
+            scope="read write",
+        ),
+    )
+
+    data = api.read("protected/resource")
+
+CRUDs handles token acquisition, caching, and refresh automatically.
 
 Databricks
 ----------
 
 Serverless OLTP Database - PostgREST
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Currently in Private Preview from Databricks, however it offers a Service URL which
 is an API that with Service Principal OAuth2 credentials can read data from the database.