Update README.md

Author: eclipseo

.github/workflows/main.yml

@@ -36,7 +36,7 @@ jobs:
        path: '.'
 
   build:
-    name: Build & Publish
+    name: Build
     runs-on: ubuntu-latest
     needs: test
     steps:

README.md

@@ -1,109 +1,187 @@
 # PyDepsDev
 
-A Python library for interacting with the Deps.dev API. Easily fetch package, version, and project data from the API.
+A Python library for interacting with Open Source Insights API (deps.dev).  
+Easily fetch package, version, project, advisory, container, and PURL data—and leverage automatic name normalization and hash encoding.
 
 ## Table of Contents
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Initialization](#initialization)
-  - [Fetching Data](#fetching-data)
-- [Contributing](#contributing)
-- [License](#license)
 
-## Installation
+- [Installation](#installation)  
+- [Quick Start](#quick-start)  
+- [Name Normalization & Hash Encoding](#name-normalization--hash-encoding)  
+- [Endpoints](#endpoints)  
+  - [Package & Version](#package--version)  
+  - [Batch Version Queries](#batch-version-queries)  
+  - [Requirements, Dependencies & Dependents](#requirements-dependencies--dependents)  
+  - [Capabilities & Similarly-Named](#capabilities--similarly-named)  
+  - [Project](#project)  
+  - [Advisories](#advisories)  
+  - [PURL Lookup](#purl-lookup)  
+  - [Container Images](#container-images)  
+- [Contributing](#contributing)  
+- [License](#license)  
 
-To install `pydepsdev`, simply run:
+## Installation
 
 ```bash
-pip3 install pydepsdev
+pip install pydepsdev
 ```
 
-## Usage
+## Quick Start
+
+```python
+import asyncio
+from pydepsdev.api import DepsdevAPI
+
+async def main():
+    # Simple init
+    api = DepsdevAPI()
+
+    # …use api methods…
 
-### Initialization
+    await api.close()
+
+asyncio.run(main())
+```
 
-Start by importing the library and initializing the main class:
+Or use as an async context manager:
 
 ```python
-from pydepsdev import DepsdevAPI
+import asyncio
+from pydepsdev.api import DepsdevAPI
 
-api = DepsdevAPI()
+async def main():
+    async with DepsdevAPI() as api:
+        pkg_info = await api.get_package("npm", "foo")
+        print(pkg_info)
+
+asyncio.run(main())
 ```
 
-### Fetching Data
+## Name Normalization & Hash Encoding
+
+- **System names** are case‐insensitive but always sent uppercase.  
+- **NuGet** package names are lowercased.  
+- **PyPI** package names are normalized per [PEP 503].  
+- When you call `query_package_versions(hash_type, hash_value, …)`, your `hash_value` is automatically Base64‐encoded before sending.
+
+## Endpoints
+
+### Package & Version
 
-The library provides methods that correspond to different endpoints in the Deps.dev API. Here's a breakdown of each method and how to use them:
+```python
+# Get basic package info + versions list
+await api.get_package(system_name: str, package_name: str)
+
+# Get metadata for a specific version
+await api.get_version(system_name: str, package_name: str, version: str)
+```
 
-1. **Get Package Information**
+### Batch Version Queries
 
-   Fetch package details including available versions.
+```python
+# One page (up to 5000) of versions
+await api.get_version_batch(
+    [(system, pkg, ver), …],
+    page_token: Optional[str] = None
+)
+
+# Retrieve ALL pages for a batch
+await api.get_all_versions_batch(
+    [(system, pkg, ver), …]
+)
+```
 
-   ```python
-   package_info = await api.get_package("system_name", "package_name")
-   ```
+### Requirements, Dependencies & Dependents
 
-2. **Get Version Information**
+```python
+# NuGet only
+await api.get_requirements("NuGet", "package_name", "version")
 
-   Fetch detailed information about a specific package version.
+# Any supported system
+await api.get_dependencies(system_name, package_name, version)
 
-   ```python
-   version_info = await api.get_version("system_name", "package_name", "version_number")
-   ```
+# Dependent counts
+await api.get_dependents(system_name, package_name, version)
+```
 
-3. **Get Requirements**
+### Capabilities & Similarly-Named
 
-   Return the requirements for a specific package version. (Note: Only available for NuGet.)
+```python
+# Go only
+await api.get_capabilities("Go", "module_path", "version")
 
-   ```python
-   requirements = await api.get_requirements("NuGet", "package_name", "version_number")
-   ```
+# Find similarly-named packages
+await api.get_similarly_named_packages(system_name, package_name)
+```
 
-4. **Get Dependencies**
+### Query Package Versions
 
-   Fetch the resolved dependency graph for a specific package version.
+```python
+# By hash (hash.value is auto base64‐encoded)
+await api.query_package_versions(
+    hash_type: str,     # e.g. "SHA256"
+    hash_value: str,    # raw hex or bytes
+    version_system: Optional[str] = None,
+    version_name:   Optional[str] = None,
+    version:        Optional[str] = None,
+)
+```
 
-   ```python
-   dependencies = await api.get_dependencies("system_name", "package_name", "version_number")
-   ```
+### Project
 
-5. **Get Project Information**
+```python
+# Single project metadata
+await api.get_project(project_id: str)
 
-   Retrieve details about projects hosted by platforms like GitHub, GitLab, or BitBucket.
+# One page of project batch
+await api.get_project_batch(
+    [project_id1, project_id2, …],
+    page_token: Optional[str] = None
+)
 
-   ```python
-   project_info = await api.get_project("project_id")
-   ```
+# Retrieve all pages
+await api.get_all_projects_batch([…])
 
-6. **Get Project Package Versions**
+# List package versions derived from a project
+await api.get_project_package_versions(project_id: str)
+```
 
-   Fetch the package versions created from a specified source code repository.
+### Advisories
 
-   ```python
-   project_package_versions = await api.get_project_package_versions("project_id")
-   ```
+```python
+# Fetch OSV advisory details
+await api.get_advisory(advisory_id: str)
+```
 
-7. **Get Advisory Details**
+### PURL Lookup
 
-   Fetch information about a security advisory from OSV.
+```python
+# Single purl
+await api.get_purl_lookup(purl: str)
 
-   ```python
-   advisory_info = await api.get_advisory("advisory_id")
-   ```
+# One page of PURL batch
+await api.get_purl_lookup_batch(
+    [purl1, purl2, …],
+    page_token: Optional[str] = None
+)
 
-8. **Query Package Versions**
+# Retrieve all pages
+await api.get_all_purl_lookup_batch([…])
+```
 
-   Query package versions based on content hash or version key.
+### Container Images
 
-   ```python
-   package_versions = await api.query_package_versions(hash_type="type", hash_value="value", version_system="system_name", version_name="name", version="version_number")
-   ```
+```python
+# Query container images by OCI chain ID
+await api.query_container_images(chain_id: str)
+```
 
-Get more informating about the query parameters and response values on the [official API documentation](https://docs.deps.dev/api/v3alpha)
+For full details on parameters and response schemas, see the [Deps.dev API docs](https://docs.deps.dev/api/v3alpha).
 
 ## Contributing
 
-We welcome contributions! If you find a bug or have suggestions, feel free to open an issue or submit a pull request.
+Contributions, issues and feature requests are welcome!  
+Feel free to check [issues page](https://github.com/eclipseo/pydepsdev/issues) or submit a pull request.
 
 ## License
-
 This project is licensed under the Apache Software License 2.0.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pydepsdev"
-version = "0.2.0"
+version = "0.2.1"
 authors = [
   { name = "Robert-André Mauchin", email = "[email protected]" }
 ]