docs: add an initial version for the README. #2

ecarrenolozano · 2025-12-05T10:53:47Z

Documentation enhancements:

Added a detailed project description outlining the purpose, features, and ideal use cases of cache-manager.
Included step-by-step installation instructions for both pip and Poetry workflows.
Added sections for configuration options, contributing guidelines, license information, and contact details to support users and potential contributors.
Structured the README with a table of contents and placeholders for code examples to improve readability and navigation.

Note: @deeenes, @npalacioescat. Could you please complete the README?.

Copilot

Pull request overview

This PR adds comprehensive documentation to the README.md, transforming it from a minimal placeholder into a detailed project guide. The README provides project description, installation instructions, usage guidelines, configuration options, and sections for examples, contributing, license, and contact information.

Key changes:

Added detailed project description explaining cache-manager's purpose and core features
Included installation instructions for both pip and Poetry workflows
Added structured sections with table of contents for improved navigation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-05T11:00:49Z

README.md

+```python
+
+```
+
+2) TODO: Add another minimal example.
+
+```python
+
+```
+
+1) TODO: Add a more complete example.
+
+```python
+
+```
+


The code block for this example is empty. Consider either adding the example code or removing this empty code block until the example is ready to be added.

Suggested change

```python

```

2) TODO: Add another minimal example.

```python

```

1) TODO: Add a more complete example.

```python

```

2) TODO: Add another minimal example.

1) TODO: Add a more complete example.

Copilot · 2025-12-05T11:00:50Z

README.md

+Run the included example script which downloads a real dataset and caches it:
+
+```bash
+python scripts/hello_cache_manager.py
+```
+


The referenced script scripts/hello_cache_manager.py does not exist in the repository. Either create this script or remove this reference until the example script is available.

Suggested change

Run the included example script which downloads a real dataset and caches it:

```bash

python scripts/hello_cache_manager.py

```

Copilot · 2025-12-05T11:00:50Z

README.md

+git clone https://github.com/saezlab/cache-manager.git
+cd cache-manager
+python -m venv .venv && source .venv/bin/activate
+pip install -e .[dev]


The command pip install -e .[dev] may not work correctly for this Poetry project. The project defines dependencies in [tool.poetry.dev-dependencies] but doesn't define a [dev] extras group. Consider using poetry install instead, or add a [tool.poetry.extras] section with a dev group that references the dev dependencies.

Suggested change

pip install -e .[dev]

poetry install

Copilot · 2025-12-05T11:00:50Z

README.md

+# cache-manager
+
+## Description
+cache-manager is a lightweight, Pythonic cache for files with a SQLite registry. It lets you:


The article should be "an" instead of "a" before "SQLite" since "SQLite" is pronounced starting with a vowel sound ("ess-cue-lite").

Suggested change

cache-manager is a lightweight, Pythonic cache for files with a SQLite registry. It lets you:

cache-manager is a lightweight, Pythonic cache for files with an SQLite registry. It lets you:

Copilot · 2025-12-05T11:00:50Z

README.md

+
+```
+
+1) TODO: Add a more complete example.


The example numbering is inconsistent. The sequence shows "1) TODO", "2) TODO", then "1) TODO" again. The third example should be numbered "3)" instead of repeating "1)".

Suggested change

1) TODO: Add a more complete example.

3) TODO: Add a more complete example.

Copilot · 2025-12-05T11:00:51Z

README.md

+```python
+


The code block for the minimal example is empty. Consider either adding a minimal code example or removing this empty code block until the example is ready to be added.

Suggested change

```python

```python

from cache_manager import Cache

# Create a cache in the default location

cache = Cache(pkg="myapp")

# Create or get a cache item for a given key

item = cache.get_or_create("myfile.txt")

# Write some data to the file

with item.open("w") as f:

f.write("hello world")

# Mark the item as ready

item.mark_ready()

Copilot · 2025-12-05T11:00:51Z

README.md

+```python
+
+```


The code block for this example is empty. Consider either adding the example code or removing this empty code block until the example is ready to be added.

Copilot · 2025-12-05T11:00:51Z

README.md

+```python
+
+```
+
+2) TODO: Add another minimal example.
+
+```python
+
+```
+
+1) TODO: Add a more complete example.
+
+```python
+
+```


The code block for this example is empty. Consider either adding the example code or removing this empty code block until the example is ready to be added.

Suggested change

```python

```

2) TODO: Add another minimal example.

```python

```

1) TODO: Add a more complete example.

```python

```

2) TODO: Add another minimal example.

1) TODO: Add a more complete example.

…thon projects.

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-05T12:02:22Z

scripts/hello_cache_manager.py

+        rows = []
+        for i, row in enumerate(reader):
+            rows.append(row)
+            if i >= 5:  # header + 5


The comment "# header + 5" is misleading. The condition if i >= 5 will break after reading 6 rows (indices 0-5), which includes the header plus 5 data rows. However, the comment at line 76 says "header + 5 rows", which correctly describes the intent. Consider updating this comment to "# indices 0-5, i.e., 6 rows total" for clarity.

Suggested change

if i >= 5: # header + 5

if i >= 5: # indices 0-5, i.e., 6 rows total (header + 5 data rows)

Copilot · 2025-12-05T12:02:23Z

README.md

+
+## Contributing
+Contributions are welcome! A typical flow:
+


The Contributing section mentions "A typical flow:" but doesn't provide the flow steps. Either remove this introductory phrase or add the actual workflow steps (e.g., fork the repo, create a branch, make changes, submit PR).

Suggested change

1. Fork the repository on GitHub.

2. Clone your fork locally.

3. Create a new branch for your feature or fix.

4. Make your changes and commit them with clear messages.

5. Push your branch to your fork on GitHub.

6. Open a pull request against the main repository.

Copilot · 2025-12-05T12:02:23Z

scripts/hello_cache_manager.py

+            try:
+                if os.path.exists(item.path):
+                    os.remove(item.path)
+            except Exception:


'except' clause does nothing but pass and there is no explanatory comment.

Suggested change

except Exception:

except Exception:

# Ignore errors during cleanup; file may not exist or be locked.

docs: add an initial version for the README.

285850e

ecarrenolozano requested a review from deeenes December 5, 2025 10:53

ecarrenolozano assigned ecarrenolozano and unassigned ecarrenolozano Dec 5, 2025

ecarrenolozano added the documentation Improvements or additions to documentation label Dec 5, 2025

ecarrenolozano linked an issue Dec 5, 2025 that may be closed by this pull request

Missing README and instructions related to this package #1

Open

ecarrenolozano requested review from Copilot and npalacioescat December 5, 2025 10:57

Copilot started reviewing on behalf of ecarrenolozano December 5, 2025 10:57 View session

Copilot finished reviewing on behalf of ecarrenolozano December 5, 2025 10:59

Copilot AI reviewed Dec 5, 2025

View reviewed changes

ecarrenolozano added 2 commits December 5, 2025 12:52

chores: replace .gitignore with the GitHub template .gitignore for py…

11538f6

…thon projects.

chores: fix numeration in example items.

c4697de

ecarrenolozano requested a review from Copilot December 5, 2025 11:55

Copilot started reviewing on behalf of ecarrenolozano December 5, 2025 11:56 View session

Copilot finished reviewing on behalf of ecarrenolozano December 5, 2025 12:01

Copilot AI reviewed Dec 5, 2025

View reviewed changes

	cache-manager is a lightweight, Pythonic cache for files with a SQLite registry. It lets you:
	cache-manager is a lightweight, Pythonic cache for files with an SQLite registry. It lets you:

	1) TODO: Add a more complete example.
	3) TODO: Add a more complete example.

-```python
+```python
+from cache_manager import Cache
+# Create a cache in the default location
+cache = Cache(pkg="myapp")
+# Create or get a cache item for a given key
+item = cache.get_or_create("myfile.txt")
+# Write some data to the file
+with item.open("w") as f:
+    f.write("hello world")
+# Mark the item as ready
+item.mark_ready()

	if i >= 5: # header + 5
	if i >= 5: # indices 0-5, i.e., 6 rows total (header + 5 data rows)

+. Fork the repository on GitHub.
+. Clone your fork locally.
+. Create a new branch for your feature or fix.
+. Make your changes and commit them with clear messages.
+. Push your branch to your fork on GitHub.
+. Open a pull request against the main repository.

	except Exception:
	except Exception:
	# Ignore errors during cleanup; file may not exist or be locked.

docs: add an initial version for the README. #2

Are you sure you want to change the base?

docs: add an initial version for the README. #2

Uh oh!

Conversation

ecarrenolozano commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 5, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ecarrenolozano commented Dec 5, 2025 •

edited

Loading