chore: inline badges

CHANGELOG.md

@@ -0,0 +1,19 @@
+- Initial release is out! (#1)
+
+# Calibrestekje 0.0.3 (2020-03-01)
+
+## Improved Documentation
+
+-   Add flask extension documentation. (#3)
+
+# Calibrestekje 0.0.2 (2020-03-01)
+
+## Improved Documentation
+
+-   Add modules API. (#2)
+
+# Calibrestekje 0.0.1 (2020-03-01)
+
+## Project announcements
+
+-   Initial release is out! (#1)

CODE_OF_CONDUCT.rst

@@ -1,111 +0,0 @@
-Introduction
-------------
-
-The Calibrestekje community is committed to providing an inclusive, safe, and
-collaborative environment for all participants, regardless of their gender,
-gender expression, race, ethnicity, religion, sexual orientation, sexual
-characteristics, physical appearance, disability, or age. We encourage every
-participant to be themselves, and must respect the rights of others. The code
-of conduct is a set of guidelines that establishes shared values and ensures
-that behaviors that may harm participants are avoided.
-
-The values of the Calibrestekje community are focused on developing both our
-individual and collective potential, supporting and empowering the most
-marginalized, mutual respect, and an anti-violence approach that favors support
-and collaboration among participants and the resolution of conflicts. A code of
-conduct helps us co-exist in a more positive way and provides individuals who
-are victims of negative behaviors with confidence that they will be supported
-by the organization and the Calibrestekje community, who respects and stands
-behind the code of conduct.
-
-The Calibrestekje community works towards providing a welcoming environment
-where participants are treated with dignity and respect and are free to be
-themselves. We encourage all participants to approach the Calibrestekje network
-with an open and positive attitude, engaging constructively with others at all
-times.
-
-Respect for Diversity & Inclusion
----------------------------------
-
-We avoid comments, actions or propaganda that encourage discrimination related
-to gender, gender expression, race, ethnicity, religion, sexual orientation,
-sexual characteristics, physical appearance, disability, or age.
-
-Respect Freedom of Expression
------------------------------
-
-We support an individual's freedom of expression, and will not make fun of
-accents or make unsolicited grammatical corrections. We will strive to better
-understand each other by not assuming experiences or beliefs, clarifying
-meanings, and making an effort to speak clearly, avoiding jargon and acronyms.
-
-Commitment to Non-Violence
---------------------------
-
-We will not engage in any type of violence or aggression, including verbal
-threats or complaints, intimidation, stalking or harassment, whether physically
-or psychologically.
-
-Rejection of Sexual Harassment
-------------------------------
-
-We understand sexual harassment as unwanted physical contact or insinuation of
-a sexual nature, as well as displaying images, drawings or visual
-representations of any kind that objectify members of any gender or reinforce
-oppression. The only exception is if this is part of a session, workshop and/or
-educational experience where showing these images is educational in nature.
-
-Respect for Privacy
--------------------
-
-We safeguard the privacy of the participants. This includes refraining from
-posting or publishing information about attendees (including names and
-affiliation) unless given clear permission, and avoid any type of unauthorized
-video, audio recording, or photography.
-
-Facilitate Participation & Collaboration
-----------------------------------------
-
-We work to create an environment that facilitates participation for all
-participants. We will not engage in sustained disruption of discussions or
-events, interrupt conversations in a way that negatively impacts collaboration,
-or engage in toxic behaviours to attract negative attention to a participant.
-
-We Care about the Integrity and Health of the Community
--------------------------------------------------------
-
-We value the health of the community and will not engage in behaviour that can
-negatively impact it. This includes contaminating food or drink with drugs, or
-inciting or insisting on the consumption of alcohol, psychoactive substances,
-etc.
-
-Support Positive Interactions Among Participants
-------------------------------------------------
-
-We are committed to engaging constructively with others at all times. We will
-not tolerate bullying, including requesting or mobilizing others, either in
-person or online, to bully others.
-
-Enforcement
------------
-
-Overseeing the code of conduct
-==============================
-
-The Calibrestekje community, composed of volunteers, oversees the code of
-conduct, including addressing all incident reports. Breaking the code of
-conduct may result in immediate expulsion from the Calibrestekje network.
-
-How to Report an Incident
-=========================
-
-If you witness an incident or are the victim of one:
-
-1. You can reach out directly via email at lukewm@riseup.net.
-
-Acknowledgements
-----------------
-
-This code of conduct is inspired by the `IFF CoC`_.
-
-.. _IFF CoC: https://www.internetfreedomfestival.org/wiki/index.php/Code_of_Conduct

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Get started
+
+Install [Tox](http://tox.readthedocs.io/).
+
+# Run tests
+
+``` bash
+$ tox -e test
+```
+
+# Lint source
+
+``` bash
+$ tox -e lint
+```
+
+# Format source
+
+``` bash
+$ tox -e format
+```
+
+# Type check source
+
+``` bash
+$ tox -e type
+```
+
+# Build the documentation
+
+``` bash
+$ tox -e docs
+$ tox -e docs-livereload
+```
+
+# Make a new release
+
+Ensure metadata for packaging is correct.
+
+``` bash
+$ tox -e metadata-release
+```
+
+Generate the changelog with the next target version.
+
+``` bash
+$ export VERSION=1.0.1 tox -e changelog
+```
+
+Make a new Git tag.
+
+``` bash
+$ git tag  -a 1.0.1
+```
+
+And finally, make a new release.
+
+``` bash
+$ tox -e release

CONTRIBUTING.rst

@@ -1,70 +0,0 @@
-Get started
------------
-
-Install `Tox`_.
-
-.. _tox: http://tox.readthedocs.io/
-
-Run tests
----------
-
-.. code-block:: bash
-
-    $ tox -e test
-
-Lint source
------------
-
-.. code-block:: bash
-
-    $ tox -e lint
-
-Format source
--------------
-
-.. code-block:: bash
-
-    $ tox -e format
-
-Type check source
------------------
-
-.. code-block:: bash
-
-    $ tox -e type
-
-Build the documentation
------------------------
-
-.. code-block:: bash
-
-    $ tox -e docs
-    $ tox -e docs-livereload
-
-
-Make a new release
-------------------
-
-Ensure metadata for packaging is correct.
-
-.. code-block:: bash
-
-    $ tox -e metadata-release
-
-Generate the changelog with the next target version.
-
-.. code-block:: bash
-
-    $ export VERSION=1.0.1 tox -e changelog
-
-Make a new Git tag.
-
-.. code-block:: bash
-
-    $ git tag  -a 1.0.1
-
-And finally, make a new release.
-
-.. code-block:: bash
-
-    $ tox -e release

MANIFEST.in

@@ -1 +1 @@
-include LICENSE README.rst CHANGELOG.rst
+include LICENSE README.md CHANGELOG.md

README.md

@@ -0,0 +1,48 @@
+# calibrestekje
+
+[![Repository license](https://img.shields.io/badge/license-GPL-brightgreen.svg)](LICENSE)
+[![PyPI package](https://badge.fury.io/py/calibrestekje.svg)](https://badge.fury.io/py/calibrestekje)
+[![Travis CI result](https://travis-ci.com/decentral1se/calibrestekje.svg?branch=master)](https://travis-ci.com/decentral1se/calibrestekje)
+[![Documentation status](https://readthedocs.org/projects/calibrestekje/badge/?version=latest)](https://calibrestekje.readthedocs.io/en/latest/)
+[![Support badge](http://img.shields.io/liberapay/patrons/decentral1se.svg?logo=liberapay)](https://liberapay.com/decentral1se)
+
+## Library prototyping based on Calibre {#introduction}
+
+Calibrestekje is a Python library which provides a way to work with the
+[Calibre](https://calibre-ebook.com/) database outside the context of
+the Calibre desktop and web interfaces.
+
+Generated [SQLAlchemy](https://docs.sqlalchemy.org/) database bindings
+(see [sqlacodegen](https://github.com/agronholm/sqlacodegen) for more)
+are provided which allow for read/write access to an existing Calibre
+database. These bindings are more fine grained than Calibres [database
+interface](https://manual.calibre-ebook.com/db_api.html) and provide
+direct access to the Database table layer. The bindings are generated
+from Calibre version `2.75.1`.
+
+A [flask](https://flask.palletsprojects.com/) extension is also provided
+for getting started with web prototyping. Please see
+[flask-calibrestekje](https://github.com/decentral1se/flask-calibrestekje)
+and [the flask usage
+documentation](https://calibrestekje.readthedocs.io/en/latest/flask.html)
+for more.
+
+### Quick Example {#example}
+
+``` python
+from calibrestekje import Book, Publisher, init_session
+
+session = init_session("sqlite:///mymetadata.db")
+
+publisher = (session.query(Publisher)
+                    .filter(Publisher.name == "MIT Press").one())
+
+books = (session.query(Book)
+                .filter(Book.publishers.contains(publisher)))
+
+print(f"Books published by MIT Press: {books.count()}")
+```
+
+### Documentation
+
+-   <https://calibrestekje.readthedocs.io/>

README.rst

@@ -1,79 +0,0 @@
-.. _header:
-
-*************
-calibrestekje
-*************
-
-.. image:: https://img.shields.io/badge/license-GPL-brightgreen.svg
-   :target: LICENSE
-   :alt: Repository license
-
-.. image:: https://badge.fury.io/py/calibrestekje.svg
-   :target: https://badge.fury.io/py/calibrestekje
-   :alt: PyPI package
-
-.. image:: https://travis-ci.com/decentral1se/calibrestekje.svg?branch=master
-   :target: https://travis-ci.com/decentral1se/calibrestekje
-   :alt: Travis CI result
-
-.. image:: https://readthedocs.org/projects/calibrestekje/badge/?version=latest
-   :target: https://calibrestekje.readthedocs.io/en/latest/
-   :alt: Documentation status
-
-.. image:: http://img.shields.io/liberapay/patrons/decentral1se.svg?logo=liberapay
-   :target: https://liberapay.com/decentral1se
-   :alt: Support badge
-
-.. _introduction:
-
-Library prototyping based on Calibre
-------------------------------------
-
-Calibrestekje is a Python library which provides a way to work with the
-`Calibre`_ database outside the context of the Calibre desktop and web
-interfaces. A set of generated `SQLAlchemy`_ bindings (see `sqlacodegen`_ for
-more) are provided which allow for the read/write access to an existing Calibre
-metadata database (a file typically called ``metadata.db``). These bindings are
-more fine grained than Calibres `database interface`_ and provide direct access
-to the Database table layer.
-
-.. _Calibre: https://calibre-ebook.com/
-.. _SQLALchemy: https://docs.sqlalchemy.org/
-.. _sqlacodegen: https://github.com/agronholm/sqlacodegen
-.. _database interface: https://manual.calibre-ebook.com/db_api.html
-.. _Relearn!: http://relearn.be/2019/
-
-.. _example:
-
-Quick Example
-*************
-
-See documentation linked below for more.
-
-.. code-block:: python
-
-    from calibrestekje import Book, Publisher, init_session
-
-    session = init_session("sqlite:///mymetadata.db")
-
-    publisher = (session.query(Publisher)
-                        .filter(Publisher.name == "MIT Press").one())
-
-    books = (session.query(Book)
-                    .filter(Book.publishers.contains(publisher)))
-
-    print(f"Books published by MIT Press: {books.count()}")
-
-.. _documentation:
-
-Documentation
-*************
-
-* https://calibrestekje.readthedocs.io/
-
-Mirroring
-*********
-
-* `hack.decentral1.se/decentral1se/calibrestekje`_
-
-.. _hack.decentral1.se/decentral1se/calibrestekje: https://hack.decentral1.se/decentral1se/calibrestekje/

docs/source/examples.rst

@@ -8,9 +8,10 @@ In order to work with Calibrestkje, you'll need to learn more about
 `SQLAlchemy`_. SQLAlchemy is a Python "Object Relational Mapper", meaning that
 it can help you write Python programs that interact with a database without
 having to write raw database queries (that is often harder to do correctly).
-The `querying`_ documentation is particularly useful. The following examples
-are laid out in a "cookbook" style. Hopefully there is something useful in here
-for you.
+The `querying`_ documentation is particularly useful. Please also see the
+:ref:`modules_api` documentation for which tables are available for import and
+use. The following examples are laid out in a "cookbook" style. Hopefully there
+is something useful in here for you.
 
 .. _SQLAlchemy: https://docs.sqlalchemy.org/en/13/
 .. _querying: https://docs.sqlalchemy.org/en/13/orm/tutorial.html#querying
@@ -48,6 +49,13 @@ it is required to run this magical incantation that is hard to remember.
 Afterwards, you'll have a new ``mytestcalibredb/metadata.db`` empty database
 which you can start to work with.
 
+If you want to run Calibre only using this new library, you can do the
+following. Otherwise, Calibre will default to the standard database location.
+
+.. code-block:: bash
+
+   $ calibre --with-library mytestcalibredb
+
 Initialising a new session
 --------------------------
 
@@ -64,7 +72,7 @@ All books without a publisher
 .. code-block:: python
 
     (session.query(Book)
-           .filter(Book.publishers == None))
+            .filter(Book.publishers == None))
 
 List of all tags that contain some pattern
 ------------------------------------------
@@ -72,7 +80,7 @@ List of all tags that contain some pattern
 .. code-block:: python
 
     (session.query(Tag)
-           .filter(Tag.name.contains("humanities")))
+            .filter(Tag.name.contains("humanities")))
 
 Adding a new tag to a book
 --------------------------
@@ -95,6 +103,6 @@ All books with multiple authors
     from sqlalchemy.sql.expression import func
 
     (session.query(Book)
-           .join(Book.authors)
-           .group_by(Book)
-           .having(func.count(Author.id) > 1))
+            .join(Book.authors)
+            .group_by(Book)
+            .having(func.count(Author.id) > 1))

docs/source/flask.rst

@@ -0,0 +1,47 @@
+.. _flasking:
+
+*******************
+Flask-Calibrestekje
+*******************
+
+A `flask`_ extension is available for prototyping new web interfaces with
+calibrestekje.
+
+.. _flask: https://flask.palletsprojects.com
+
+To get started you'll need to install the extension.
+
+.. code-block:: bash
+
+    $ pip install flask-calibrestekje
+
+Then create an ``app.cfg`` file with the following contents.
+
+.. code-block:: cfg
+
+    CALIBRESTEKJE_SQLITE_URL = "sqlite:///mymetadata.db"
+
+Create your Flask application in an ``app.py``.
+
+.. code-block:: python
+
+    from calibrestekje import Book
+    from flask import Flask, jsonify
+
+    from flask_calibrestekje import CalibreStekje
+
+    app = Flask(__name__)
+    app.config.from_pyfile("app.cfg")
+
+    db = CalibreStekje(app)
+
+    @app.route("/")
+    def home():
+        return jsonify({"book-count": db.session.query(Book).count()})
+
+And finally, run your application.
+
+.. code-block:: bash
+
+    $ export FLASK_APP=app.py
+    $ flask run

docs/source/forking.rst

@@ -1,50 +0,0 @@
-.. _forking:
-
-*******
-Forking
-*******
-
-If you'd like to go beyond Calibre and embark on a new experimental library but
-do not want to have to re-invent the database schema, you can get `SQLAlchemy`_
-ecosystem tooling to output SQLAlchemy schemas definition based on Calibre but
-ones which you can change yourself. This makes it possible to add new columns
-and tables to your new database.
-
-.. _SQLALchemy: https://docs.sqlalchemy.org/
-
-To get started, you would run the following commands.
-
-.. code-block:: bash
-
-    $ pip install sqlacodegen
-    $ sqlacodegen --noviews "sqlite:///path_to_my_calibre_metadata.db" > mynewdb.py
-
-If you look in ``mynewdb.py``, Sqlacodegen may have included a table called
-``t_sqlite_sequence``. You will want to remove this as I've only seen errors
-related to this table for some reasons which are not clear now.
-
-Feel free to add, delete and change columns and tables in the ``mynewdb.py``
-file! It will be used to generate a brand new Sqlite database in which you have
-a free hand to design a model for whatever ideas you might want to work with in
-your new library software.
-
-To generate the new Sqlite database, run the following.
-
-.. code-block:: python
-
-    from mynewdb import Base
-    from sqlalchemy import create_engine
-
-    engine = create_engine('sqlite:///mynewdb.db')
-
-    Base.metadata.create_all(engine)
-
-As a final check, it is then possible to investigate your new database with
-`sqlitebrowser`_ to check that the new database matches what you have defined
-in your ``mynewdb.py``.
-
-.. _sqlitebrowser: https://sqlitebrowser.org/
-
-.. code-block:: bash
-
-    sqlitebrowser mynewdb.db

docs/source/index.rst

@@ -7,7 +7,8 @@
 
    install
    examples
-   forking
+   modules-api
+   flask
    upgrade
    contribute
    changelog

docs/source/modules-api.rst

@@ -0,0 +1,17 @@
+.. _modules_api:
+
+***********
+Modules API
+***********
+
+User facing API
+---------------
+
+.. automodule:: calibrestekje.api
+   :members: init_session
+
+Database bindings
+-----------------
+
+.. automodule:: calibrestekje.bindings
+   :members:

pyproject.toml

@@ -13,7 +13,7 @@ include = '\.pyi?$'
 
 [tool.towncrier]
 directory = "changelog/"
-filename = "CHANGELOG.rst"
+filename = "CHANGELOG.md"
 package = "calibrestekje"
 package_dir = "calibrestekje"
 

setup.cfg

@@ -15,16 +15,16 @@ include_trailing_comma = True
 [metadata]
 name = calibrestekje
 author = decentral1se
-author_email = lukewm@riseup.net
+author_email = cellarspoon@riseup.net
 maintainer = decentral1se
-maintainer_email = lukewm@riseup.net
+maintainer_email = cellarspoon@riseup.net
 url = https://github.com/decentral1se/calibrestekje
 project_urls =
-  Source Code = https://github.com/decentral1se/calibrestekje
+  Source Code = https://git.coopcloud.tech/decentral1se/calibrestekje
   Documentation = https://calibrestekje.readthedocs.io/
   Maintainer Support = https://liberapay.com/decentral1se/
 description = Library prototyping based on Calibre.
-long_description = file: README.rst
+long_description = file: README.md
 license = GPLv3
 license_file = LICENSE
 classifiers =