doc

AUTHORS.md

@@ -2,6 +2,7 @@
 
 ## Current maintainers:
 
+- Ido Shraga
 - Andrey Shpak
 
 This project is made by incredible authors:

CONTRIBUTING.md

@@ -200,7 +200,7 @@ Any pull requests without tests will take longer to be integrated and might be r
 
 [pre-commit]: https://pre-commit.com/
 
-[GitHub actions]: https://github.com/MongoEngine/flask-mongoengine/actions
+[GitHub actions]: https://github.com/idoshr/flask-mongoengine/actions
 
 [Flask]: https://github.com/pallets/flask
 

LICENSE.md

@@ -1,6 +1,6 @@
 # BSD 3-Clause License
 
-Copyright (c) 2010-2023, the respective contributors, as shown by
+Copyright (c) 2010-2024, the respective contributors, as shown by
 the [AUTHORS.md](AUTHORS.md) file.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,11 +1,11 @@
 # Flask-MongoEngine
 
-[![PyPI version](https://badge.fury.io/py/flask-mongoengine.svg)](https://badge.fury.io/py/flask-mongoengine)
-[![CI Tests](https://github.com/MongoEngine/flask-mongoengine/actions/workflows/tests.yml/badge.svg)](https://github.com/MongoEngine/flask-mongoengine/actions/workflows/tests.yml)
+[![PyPI version](https://badge.fury.io/py/flask-mongoengine-2.svg)](https://badge.fury.io/py/flask-mongoengine-2)
+[![CI Tests](https://github.com/idoshr/flask-mongoengine/actions/workflows/tests.yml/badge.svg)](https://github.com/flask/flask-mongoengine/actions/workflows/tests.yml)
 [![Documentation Status](https://readthedocs.org/projects/flask-mongoengine/badge/?version=latest)](http://docs.mongoengine.org/projects/flask-mongoengine/en/latest/?badge=latest)
-[![Maintainability](https://api.codeclimate.com/v1/badges/6fb8ae00b1008f5f1b20/maintainability)](https://codeclimate.com/github/MongoEngine/flask-mongoengine/maintainability)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6fb8ae00b1008f5f1b20/maintainability)](https://codeclimate.com/github/idoshr/flask-mongoengine/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/6fb8ae00b1008f5f1b20/test_coverage)](https://codeclimate.com/github/MongoEngine/flask-mongoengine/test_coverage)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/flask-mongoengine)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/flask-mongoengine-2)
 
 Flask-MongoEngine is a Flask extension that provides integration with [MongoEngine],
 [WtfForms] and [FlaskDebugToolbar].

docs/conf.py

@@ -49,18 +49,18 @@
 master_doc = "index"
 
 # General information about the project.
-project = "Flask-MongoEngine"
-copyright = "2010-2020, Streetlife and others"
+project = "Flask-MongoEngine-2"
+copyright = "2010-2024, Streetlife and others"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 
 # The short X.Y version.
-version = v("flask_mongoengine")
+version = v("flask_mongoengine-2")
 # The full version, including alpha/beta/rc tags.
-release = v("flask_mongoengine")
+release = v("flask_mongoengine-2")
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -240,8 +240,8 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
-    "flask": ("https://flask.palletsprojects.com/en/2.2.x/", None),
-    "werkzeug": ("https://werkzeug.palletsprojects.com/en/2.1.x/", None),
+    "flask": ("https://flask.palletsprojects.com/en/3.0.x/", None),
+    "werkzeug": ("https://werkzeug.palletsprojects.com/en/3.0.x/", None),
     "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
     "mongoengine": ("https://docs.mongoengine.org/", None),
     "wtforms": ("https://wtforms.readthedocs.io/en/3.0.x/", None),

docs/index.rst

@@ -14,7 +14,7 @@ You can also use `WTForms <http://wtforms.simplecodes.com/>`_ as model forms for
    db_model
    forms
    migration_to_v2
-   custom_queryset
+   pagination
    custom_json_encoder
    wtf_forms
    session_interface

docs/pagination.md

@@ -0,0 +1,165 @@
+# Pagination
+
+flask-mongoengine attaches the following methods to Mongoengine's default QuerySet:
+
+* **paginate**: paginates the QuerySet. Takes two required arguments, *page* and *per_page*.
+   And two optional arguments: *max_depth*, *first_page_index*.
+* **paginate_by_keyset**: paginates the QuerySet. Takes two required arguments,
+  *per_page* and *field_filter_by*.
+  from the second page you need also the last id of the previous page.
+  Arguments: *per_page*, *field_filter_by*, *last_field_value*.
+* **paginate_field**: paginates a field from one document in the QuerySet.
+  Arguments: *field_name*, *doc_id*, *page*, *per_page*.
+  And two optional arguments: *total*, *first_page_index*
+
+## Offset pagination
+
+Offset API pagination is the most common form of API pagination.
+It’s also sometimes called page-based pagination.
+An API endpoint accepts a parameter for a page number and per page then
+returns that page values.
+
+### Example 1
+
+```python
+from flask import request
+
+page = request.args.get('page', 1, type=int)
+per_page = request.args.get('per_page', 10, type=int)
+
+paginated_todos = Todo.objects.paginate(page=page, per_page=per_page)
+
+```
+
+### Example 2
+
+```python
+from flask import request
+from flask_mongoengine import Pagination
+
+page = request.args.get('page', 1, type=int)
+per_page = request.args.get('per_page', 10, type=int)
+
+Pagination(Todo.objects, page=page, per_page=10)
+```
+
+## Keyset pagination
+
+Keyset-based API pagination is when an API provides a key parameter that
+delineates the query results.
+One example is if an API is sorted by ID, one key parameter could be since_id.
+
+Keyset pagination is a great way to paginate through a large dataset
+without having to worry about the page number.
+It also allows for a more consistent user experience as the user can
+always see the same results when they go to the next page.
+
+### Example 1
+
+```python
+from flask import request
+
+field_filter_by = '_id'
+per_page = request.args.get('per_page', 10, type=int)
+
+paginated_todos = Todo.objects.paginate_by_keyset(per_page=per_page, field_filter_by=field_filter_by)
+
+# PAGE 2
+paginated_todos_2 = Todo.objects.paginate_by_keyset(per_page=per_page, field_filter_by=field_filter_by,
+                                                    last_field_value='value_of last page')
+```
+
+### Example 2
+
+```python
+from flask import request
+from flask_mongoengine import KeysetPagination
+
+field_filter_by = '_id'
+per_page = request.args.get('per_page', 10, type=int)
+
+
+KeysetPagination(Todo.objects, per_page=per_page, field_filter_by=field_filter_by)
+```
+
+## List field pagination
+
+List field pagination is when an API provides a key parameter that is
+the field name that is list of values and paginate on this list.
+
+## Example 1
+
+```python
+from flask import request
+
+page = request.args.get('page', 1, type=int)
+per_page = request.args.get('per_page', 10, type=int)
+todo_id = request.args.get('todo_id', 10)
+
+todo = Todo.objects.get_or_404(_id=todo_id)
+paginated_tags = todo.paginate_field(field_name='tags', page=page, per_page=per_page)
+```
+
+## Example 2
+
+```python
+from flask import request
+
+page = request.args.get('page', 1, type=int)
+per_page = request.args.get('per_page', 10, type=int)
+todo_id = request.args.get('todo_id', 10)
+
+
+paginated_tags = Todo.paginate_field(Todo.objects, doc_id=todo_id, field_name='tags',
+                                     page=page, per_page=per_page)
+```
+
+## Example 3
+
+```python
+from flask import request
+from flask_mongoengine import ListFieldPagination
+
+page = request.args.get('page', 1, type=int)
+per_page = request.args.get('per_page', 10, type=int)
+todo_id = request.args.get('todo_id', 10)
+
+
+ListFieldPagination(Todo.objects, doc_id=todo_id, field_name='tags',
+                    page=page, per_page=per_page)
+```
+
+## Render page with pagination
+
+Properties of the pagination object include: iter_pages, next, prev, has_next,
+has_prev, next_num, prev_num.
+
+In the template:
+
+```html
+{# Display a page of todos #}
+<ul>
+    {% for todo in paginated_todos.items %}
+        <li>{{ todo.title }}</li>
+    {% endfor %}
+</ul>
+
+{# Macro for creating navigation links #}
+{% macro render_navigation(pagination, endpoint) %}
+  <div class=pagination>
+  {% for page in pagination.iter_pages() %}
+    {% if page %}
+      {% if page != pagination.page %}
+        <a href="{{ url_for(endpoint, page=page) }}">{{ page }}</a>
+      {% else %}
+        <strong>{{ page }}</strong>
+      {% endif %}
+    {% else %}
+      <span class=ellipsis>…</span>
+    {% endif %}
+  {% endfor %}
+  </div>
+{% endmacro %}
+
+{{ render_navigation(paginated_todos, 'view_todos') }}
+```

pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-name = "flask-mongoengine"
+name = "flask-mongoengin-2"
 description = "Flask extension that provides integration with MongoEngine and WTF model forms."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -42,6 +42,7 @@ authors = [
   {name = "Ross Lawley", email = "[email protected]"}
 ]
 maintainers = [
+  {name = "Ido Shraga", email = "[email protected]"},
   {name = "Andrey Shpak", email = "[email protected]"}
 ]
 dynamic = ["version"]
@@ -73,10 +74,10 @@ legacy-dev = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/MongoEngine/flask-mongoengine"
+Homepage = "https://github.com/idoshr/flask-mongoengine"
 Documentation = "http://docs.mongoengine.org/projects/flask-mongoengine/en/latest/"
-Repository = "https://github.com/MongoEngine/flask-mongoengine"
-Changelog = "https://github.com/MongoEngine/flask-mongoengine/releases"
+Repository = "https://github.com/idoshr/flask-mongoengine"
+Changelog = "https://github.com/idoshr/flask-mongoengine/releases"
 
 [build-system]
 requires = [
@@ -99,7 +100,7 @@ write_to = "flask_mongoengine/_version.py"
 
 [tool.black]
 line-length = 88
-target-version = ['py37']
+target-version = ['py38']
 exclude = '''
 /(
     \.eggs