Feature/new readme (#7)

Adds a new readme with detailed information about the project.

.github/workflows/poetry-pytest.yml

@@ -49,7 +49,7 @@ jobs:
         uses: actions/cache@v3.3.1
         with:
           path: .venv
-          key: pydeps-${{ hashFiles('**/poetry.lock') }}
+          key: pydeps-${{ hashFiles('**/poetry.lock') }}-${{ matrix.python-version }}
 
       - run: poetry install --no-interaction --no-root --with=dev
         if: steps.cache-deps.outputs.cache-hit != 'true'

CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to sqlalchemy-crud
+
+Thank you for considering contributing to sqlalchemy-crud!
+I appreciate your interest in making this library better.
+By contributing, you enhance its features, fix issues, 
+and improve overall code quality.
+
+To contribute to sqlalchemy-crud, 
+please follow the guidelines outlined in this document. 
+By adhering to these guidelines, 
+you ensure a smooth and efficient collaboration process.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Reporting Issues](#reporting-issues)
+- [Feature Requests](#feature-requests)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Code Formatting](#code-formatting)
+- [Pull Requests](#pull-requests)
+- [License](#license)
+
+## Code of Conduct
+
+We strive to maintain a friendly and inclusive community. 
+
+## Reporting Issues
+
+If you encounter any issues or bugs while using sqlalchemy-crud, please help us improve by reporting them. To report an issue:
+
+1. Check the existing issues to ensure it hasn't already been reported.
+2. Create a new issue, providing a clear and descriptive title.
+3. Describe the issue in detail, including steps to reproduce it, if applicable.
+4. Include any relevant error messages or screenshots.
+
+## Feature Requests
+
+We welcome feature requests that can enhance sqlalchemy-crud. To submit a feature request:
+
+1. Check the existing feature requests to avoid duplicates.
+2. Create a new feature request, providing a concise and descriptive title.
+3. Clearly explain the proposed feature and its potential benefits.
+
+## Development Setup
+
+To set up sqlalchemy-crud for local development, follow these steps:
+
+1. Fork the repository on GitHub.
+2. Clone your forked repository to your local machine.
+3. Install the project dependencies using `poetry install --no-root --with=dev`.
+5. Create a new branch for your changes: `git checkout -b my-feature-branch`.
+
+## Making Changes
+
+When making changes to the sqlalchemy-crud library, please keep the following guidelines in mind:
+
+1. Follow the existing code style and conventions.
+2. Write clear and concise commit messages.
+3. Keep each commit focused on a specific change or improvement.
+4. Test your changes thoroughly before submitting a pull request.
+5. Document any new features, modifications, or additions.
+
+## Testing
+
+We maintain a comprehensive test suite for sqlalchemy-crud to ensure its stability and reliability. Before submitting your changes, please run the tests locally using the command `poetry run pytest`. Make sure all existing tests pass and consider adding new tests for the changes you made, if applicable.
+
+## Code Formatting
+
+> you can have any color you want as long as it's black
+
+We use the [black](https://github.com/psf/black) code formatter to maintain consistent code style throughout the project. To format your code, run `poetry run black .` in the project's root directory. Ensure that your changes conform to the formatting guidelines.
+
+## Pull Requests
+
+When you're ready to contribute your changes, submit a pull request (PR) to the main repository. Please include the following information in your PR:
+
+1. A clear and descriptive title.
+2. Detailed description of the changes made.
+3. Reference any related issues or feature requests.
+4. Ensure that all tests pass.
+5. Make sure the code is properly formatted.
+
+I will review your PR, provide feedback, 
+and work with you to address any necessary changes. 
+Once approved, I'll merge your changes into the main repository.
+
+## License
+
+By contributing to sqlalchemy-crud, 
+you agree that your contributions will be licensed under 
+the [MIT License](LICENSE).

README.md

@@ -3,4 +3,116 @@
 [![.github/workflows/poetry-pytest.yml](https://github.com/cblack34/sqlalchemy-crud/actions/workflows/poetry-pytest.yml/badge.svg?event=push)](https://github.com/cblack34/sqlalchemy-crud/actions/workflows/poetry-pytest.yml)
 [![codecov](https://codecov.io/gh/cblack34/sqlalchemy-crud/branch/master/graph/badge.svg?token=230RWC83HD)](https://codecov.io/gh/cblack34/sqlalchemy-crud)
 
-Basic C.R.U.D for SQLAlchemy models
+
+sqlalchemy-crud is a Python library that takes the pain out of performing common CRUD operations on SQLAlchemy models. It provides a simple and intuitive interface to create, read, update, and delete records in your database.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage Examples](#usage-examples)
+- [Getting Started](#getting-started)
+- [Contributing](#contributing)
+- [Testing](#testing)
+- [Compatibility](#compatibility)
+- [License](#license)
+- [Versioning](#versioning)
+- [Authors and Acknowledgments](#authors-and-acknowledgments)
+
+## Installation
+
+You can easily install sqlalchemy-crud using Poetry, a dependency management tool for Python:
+
+```shell
+$ poetry add sqlalchemy-crud
+```
+
+Make sure you have Python 3.8, 3.9, 3.10, or 3.11 installed.
+
+## Usage Examples
+
+```python
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy_crud import crud
+
+from my_app.models import MyModel
+
+# Set up the SQLAlchemy session
+engine = create_engine("sqlite:///database.db")
+Session = sessionmaker(bind=engine)
+db = Session()
+
+# Create a new object
+model = crud.create_model(db, MyModel, schema={"name": "John Doe"})
+
+# Retrieve all objects
+models = crud.get_models(db, MyModel)
+
+# Retrieve an object by ID
+model = crud.get_model(db, MyModel, model_id=1)
+
+# Retrieve objects by a specific attribute
+models = crud.get_models_by_attribute(db, MyModel, attribute="name", value="John Doe")
+model = crud.get_model_by_attribute(db, MyModel, attribute="uuid", value="123e4567-e89b-12d3-a456-426614174000")
+
+# Update an object
+model = crud.update_model(db, MyModel, model_id=1, schema={"name": "Jane Doe"})
+
+# Delete an object
+crud.delete_model(db, MyModel, model_id=1)
+```
+
+## Getting Started
+
+To get started with sqlalchemy-crud, follow these steps:
+
+1. Install the library using the instructions provided in the [Installation](#installation) section.
+2. Import the necessary modules and create a SQLAlchemy session.
+3. Use the CRUD functions (`create_model`, `get_model`, `update_model`, `delete_model`, etc.) to perform operations on your SQLAlchemy models.
+4. Refer to the [Usage Examples](#usage-examples) section for more detailed examples and code snippets.
+
+## Contributing
+
+I welcome contributions from the community! If you'd like to contribute to sqlalchemy-crud, please follow the guidelines outlined in [CONTRIBUTING.md](https://example.com/contributing).
+
+## Testing
+
+To run the tests for sqlalchemy-crud, execute the following command:
+
+```shell
+$ poetry run pytest
+```
+
+[//]: # (## Code Quality)
+
+[//]: # ()
+[//]: # (The library adheres to high code quality standards. We use black for code formatting, pylint for static analysis, and pytest-cov for code coverage. To ensure code quality, run the following command:)
+
+[//]: # ()
+[//]: # (```shell)
+
+[//]: # ($ poetry run pylint sqlalchemy_crud tests)
+
+[//]: # (```)
+
+## Compatibility
+
+sqlalchemy-crud is compatible with Python 3.8, 3.9, 3.10, and 3.11. 
+It works with SQLAlchemy 1.3.19 up to but excluding (<) 2.
+
+## License
+
+This library is released under the MIT License. See the [LICENSE](https://example.com/license) file for more details.
+
+## Versioning
+
+this project follows semantic versioning for sqlalchemy-crud releases.
+
+## Authors and Acknowledgments
+
+sqlalchemy-crud is maintained by Clayton Black. 
+
+Thank you to all the contributors to open-source software.  
+Not only do I use a lot of it, but I learn a lot from it as well.
+
+I hope you find sqlalchemy-crud useful in your projects and appreciate your feedback and contributions!

pyproject.toml

@@ -12,7 +12,7 @@ readme = "README.md"
 
 [tool.poetry.dependencies]
 python = "^3.8"
-SQLAlchemy = "^1.3.19"
+SQLAlchemy = ">=1.3.19, <2.0.0"
 py = "^1.11.0"
 toml = "^0.10.2"