From 43b9a5c015344fe189f89b5a5c64df82def2cc9b Mon Sep 17 00:00:00 2001 From: Subhash Bhushan Date: Thu, 20 Jun 2024 18:08:48 -0700 Subject: [PATCH] Update README --- LICENSE | 2 +- README.md | 92 +++++++++++++++++++++ README.rst | 50 ----------- docs/community/contributing.md | 12 +-- docs/guides/domain-definition/aggregates.md | 10 +-- mkdocs.yml | 9 +- 6 files changed, 113 insertions(+), 62 deletions(-) create mode 100644 README.md delete mode 100644 README.rst diff --git a/LICENSE b/LICENSE index 69b98a34..5df690d8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2018-Present, Subhash Bhushan C. +Copyright (c) 2018-2024, Subhash Bhushan C. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following diff --git a/README.md b/README.md new file mode 100644 index 00000000..63f069f7 --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# Protean + +**Protean** is an opinionated and pragmatic framework for building event-driven applications using the CQRS pattern. + +[![Release](https://img.shields.io/pypi/v/protean?label=Release&style=flat-square)](https://pypi.org/project/protean/) +[![Build Status](https://github.com/proteanhq/protean/actions/workflows/ci.yml/badge.svg)](https://github.com/proteanhq/protean/actions/workflows/ci.yml) +[![Coverage](https://codecov.io/gh/proteanhq/protean/graph/badge.svg?token=0sFuFdLBOx)](https://codecov.io/gh/proteanhq/protean) + +## Installation + +Protean is available on PyPI: + +```console +$ python -m pip install protean +``` + +Protean officially supports Python 3.11+. + +## Quick Start + +```python +from protean import Domain +from protean.fields import String, Text + +domain = Domain(__file__, "Publishing") + +@domain.aggregate +class Post: + title = String(required=True, max_length=1000) + slug = String(required=True, max_length=1024) + content = Text(required=True) + +domain.init() +with domain.domain_context(): + post = Post( + title="Hello World", + slug="hello-world", + content="Lorem Ipsum ..." + ) + + domain.repository_for(Post).add(post) +``` + +## Documentation + +Online docs are available at https://docs.proteanhq.com. + +## Contributing + +1. Check for open issues or open a fresh issue to start a discussion + around a feature idea or a bug. +2. Fork [the repository](https://github.com/proteanhq/protean) on + GitHub, branch off `main` and start making your changes. +3. Write a test which shows that the bug was fixed or that the feature + works as expected. +4. Send a pull request and bug the maintainer until it gets merged and + published. + +For more information, please check out the +[contributing guidelines](https://docs.proteanhq.com/community/contributing/). + +## License + +BSD 3-Clause License + +Copyright (c) 2018-2024, Subhash Bhushan C. +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this +list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, +this list of conditions and the following disclaimer in the documentation +and/or other materials provided with the distribution. + +* Neither the name of the copyright holder nor the names of its contributors +may be used to endorse or promote products derived from this software +without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.rst b/README.rst deleted file mode 100644 index 751e3c4a..00000000 --- a/README.rst +++ /dev/null @@ -1,50 +0,0 @@ -******************************************************** -Protean: The Domain-Centric, Antifragile Framework -******************************************************** - -Protean helps you build software on architecture stacks that need to survive in the ever changing technology landscape. - -.. image:: https://github.com/proteanhq/protean/actions/workflows/ci.yml/badge.svg?branch=master - :target: https://github.com/proteanhq/protean/actions - :alt: Build Status -.. image:: https://codecov.io/gh/proteanhq/protean/graph/badge.svg?token=0sFuFdLBOx - :target: https://codecov.io/gh/proteanhq/protean - :alt: Coverage -.. image:: https://pyup.io/repos/github/proteanhq/protean/shield.svg - :target: https://pyup.io/repos/github/proteanhq/protean/ - :alt: Updates - -Installation -############ - -:: - - pip install protean - -Documentation -############# - -Online docs are available at: https://protean.readthedocs.io/en/latest/ - -How to Contribute -################# - -1. Check for open issues or open a fresh issue to start a discussion - around a feature idea or a bug. -2. Fork [the repository](https://github.com/proteanhq/protean) on - GitHub to start making your changes to the **master** branch (or - branch off of it). -3. Write a test which shows that the bug was fixed or that the feature - works as expected. -4. Send a pull request and bug the maintainer until it gets merged and - published. :) Make sure to add yourself to - [AUTHORS](https://github.com/proteanhq/protean/blob/master/AUTHORS.rst). - -On shoulders of giants... -######################### - -Protean is not built in a vacuum. Principles and philosophies that Protean espouses are contributions from multiple sources, especially the Open Source Community. It not only refers to well-published architectural ideas and design patterns but also heavily draws inspiration from concrete implementations. - -Specifically, Protean is majorly influenced by the venerable Django Framework, and that reflects in many aspects of its underlying constructs and documentation. Thank you, Django, and the Python community, for showing what's possible. - -[ ~ Dependencies scanned by PyUp.io ~ ] diff --git a/docs/community/contributing.md b/docs/community/contributing.md index 012eef39..7c947306 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -72,7 +72,7 @@ without your patch. Run the tests as described below. - Push your commits to your fork on GitHub and [create a pull request]( https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/ proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). -Link to the issue being addressed with `fixes #123` or `closes #123` in the pull request. +- Link to the issue being addressed with `fixes #123` or `closes #123` in the pull request. ```sh $ git push --set-upstream fork your-branch-name @@ -86,13 +86,15 @@ Run the basic test suite with: $ protean test ``` -This runs the basic tests for the current environment, which is usually sufficient. If you want to run -the full test suite, you can sep up dependent services locally with docker: +This runs the basic tests for the current environment, which is usually +sufficient. If you want to run the full test suite, you can sep up +dependent services locally with docker: ```sh $ make up $ protean test -c FULL ``` -Running a full test will also generate a coverage report as part of test output. Writing tests for lines -that do not have coverage is a great way to start contributing. +Running a full test will also generate a coverage report as part of test +output. Writing tests for lines that do not have coverage is a great way to +start contributing. diff --git a/docs/guides/domain-definition/aggregates.md b/docs/guides/domain-definition/aggregates.md index 33dc4a8e..bf723803 100644 --- a/docs/guides/domain-definition/aggregates.md +++ b/docs/guides/domain-definition/aggregates.md @@ -197,9 +197,11 @@ below, `Post` has exactly one `Statistic` record associated with it. ``` ```shell ->>> post = Post(title='Foo') ->>> post.stats = Statistic(likes=10, dislikes=1) ->>> current_domain.repository_for(Post).add(post) +In [1]: post = Post(title='Foo') + +In [2]: post.stats = Statistic(likes=10, dislikes=1) + +In [3]: current_domain.repository_for(Post).add(post) ``` ### `HasMany` @@ -211,8 +213,6 @@ below, `Post` has exactly one `Statistic` record associated with it. Below is an example of adding multiple comments to the domain defined above: ```shell -❯ protean shell --domain docs_src/guides/domain-definition/008.py -... In [1]: from protean.globals import current_domain In [2]: post = Post(title='Foo') diff --git a/mkdocs.yml b/mkdocs.yml index f8a3e47e..51596ba5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,9 @@ repo_name: proteanhq/protean repo_url: https://github.com/proteanhq/protean theme: name: material + font: + text: Inter + code: JetBrains Mono palette: - media: '(prefers-color-scheme: light)' scheme: default @@ -36,6 +39,8 @@ theme: - content.code.annotate - content.code.copy - content.code.select +plugins: + - privacy markdown_extensions: - admonition - attr_list @@ -200,4 +205,6 @@ nav: # - changelog.md - Community: - community/index.md - - community/contributing.md \ No newline at end of file + - community/contributing.md +extra_css: + - stylesheets/extra.css \ No newline at end of file