diff options
| author | CoprDistGit <infra@openeuler.org> | 2023-05-05 12:24:53 +0000 |
|---|---|---|
| committer | CoprDistGit <infra@openeuler.org> | 2023-05-05 12:24:53 +0000 |
| commit | 36b7e224bf4d1aa6b565a0fa163947fc49984d39 (patch) | |
| tree | 594dacec6ed1d536e72f649ba8e450d4e4fe0352 | |
| parent | 496b4a7e1cf854531c13503b6e3ed1b4b856b03b (diff) | |
automatic import of python-falocalrepo-serveropeneuler20.03
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-falocalrepo-server.spec | 1461 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 1463 insertions, 0 deletions
@@ -0,0 +1 @@ +/falocalrepo_server-3.3.3.tar.gz diff --git a/python-falocalrepo-server.spec b/python-falocalrepo-server.spec new file mode 100644 index 0000000..58f3580 --- /dev/null +++ b/python-falocalrepo-server.spec @@ -0,0 +1,1461 @@ +%global _empty_manifest_terminate_build 0 +Name: python-falocalrepo-server +Version: 3.3.3 +Release: 1 +Summary: Web interface for falocalrepo. +License: EUPL-1.2 +URL: https://github.com/FurryCoders/falocalrepo-server +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/62/16/f484dd08511465adfc829ea1df61678a67e1354a8e6ffe57376dba92c829/falocalrepo_server-3.3.3.tar.gz +BuildArch: noarch + +Requires: python3-falocalrepo-database +Requires: python3-chardet +Requires: python3-pillow +Requires: python3-fastapi +Requires: python3-uvicorn +Requires: python3-Jinja2 +Requires: python3-click +Requires: python3-click-help-colors +Requires: python3-htmlmin +Requires: python3-beautifulsoup4 +Requires: python3-lxml +Requires: python3-bbcode + +%description +<div align="center"> + +<img alt="logo" width="400" src="https://raw.githubusercontent.com/FurryCoders/Logos/main/logos/falocalrepo-server-transparent.png"> + +# FALocalRepo-Server + +Web interface for [falocalrepo](https://pypi.org/project/falocalrepo/). + +[](https://github.com/FurryCoders/falocalrepo-server) +[](https://pypi.org/project/falocalrepo-server/) +[](https://www.python.org) +[](https://getbootstrap.com) + +</div> + +## Installation & Requirements + +To install the program it is sufficient to use Python pip and get the package `falocalrepo-server`. + +```shell +pip install falocalrepo-server +``` + +Python 3.10 or above is needed to run this program, all other dependencies are handled by pip during installation. For +information on how to install Python on your computer, refer to the official +website [Python.org](https://www.python.org/). + +For the program to run, a properly formatted database created by falocalrepo needs to be present in the same folder. + +The styling is based on the [Boostrap CSS framework](https://getbootstrap.com). + +_Note:_ When upgrading to a new version the styling may be broken to due to the browser using the old stylesheet in its +cache. To fix it, simply delete the browser cache to fetch the new version.f + +## Usage + +``` +falocalrepo-server <database> [--host HOST] [--port PORT] [--ssl-cert SSL_CERT] [--ssl-key SSL_KEY] + [--redirect-http REDIRECT_PORT] [--auth <username>:<password>] [--precache] [--no-browser] +``` + +The server needs one argument pointing at the location of a valid [falocalrepo](https://pypi.org/project/falocalrepo/) +database and accepts optional arguments to manually set host, port, and an SSL certificate with key. By default, the +server is run on 0.0.0.0:80 for HTTP (without certificate) and 0.0.0.0:443 for HTTPS (with certificate). + +The `--precache` options can be used to prepare an initial cache of results from the database to speed up searches. + +When the app has finished loading, it automatically opens a browser window. To avoid this, use the `--no-browser` +option. + +### Redirect Mode + +The optional `--redirect-http` argument changes the app mode to redirection. In this mode the app runs a tiny server +that redirects all HTTP requests it receives on `http://HOST:PORT` to `https://HOST:REDIRECT_PORT`. + +_Note:_ In redirect mode the `database` argument is not checked, so a simple `.` is sufficient.<br/> +_Note:_ In redirect mode the app does not operate the database portion of the server. To run in redirect and server +mode, two separate instances of the program are needed. + +Once the server is running the web app can be accessed at the address shown in the terminal. + +### Authentication + +The `--auth` option allows setting up a username and password to access the server using the HTTP Basic authentication +protocol. + +### Arguments + +| Argument | Default | +|-------------------|--------------------------------------------------| +| `database` | None, mandatory argument | +| `--host` | 0.0.0.0 | +| `--port` | 80 if no SSL certificate is given, 443 otherwise | +| `--ssl-cert` | None | +| `--ssl-key` | None | +| `--redirect-http` | None | +| `--auth` | None | +| `--precache` | False | +| `--no-browser` | True | + +### Examples + +```shell +# Launch an HTTP server reachable from other machines using the server's hostname/IP +falocalrepo-server ~/FA.db +``` + +```shell +# Launch a localhost-only server on port 8080 +falocalrepo-server ~/FA.db --host 127.0.0.1 --port 8080 +``` + +```shell +# Launch a redirect server that listens to port 80 and redirects to port 443 on host 0.0.0.0 +falocalrepo-server . --host 0.0.0.0 --port 80 --redirect-htpp 443 +``` + +```shell +# Launch a server with basic authentication using 'mickey' as username and 'mouse' as password +falocalrepo-server ~/FA.db --auth mickey:mouse +``` + +```shell +# Launch an HTTPS server reachable from other machines using the server's hostname/IP +falocalrepo-server ~/FA.db --ssl-cert ~/FA.certificates/certificate.crt --ssl-key ~/FA.certificates/private.key +``` + +```shell +# Launch a localhost-only HTTPS server on port 8443 +falocalrepo-server ~/FA.db --host 127.0.0.1 --port 8443 --ssl-cert ~/FA.certificates/certificate.crt --ssl-key ~/FA.certificates/private.key +``` + +## Routes + +_Note:_ All the following paths are meant as paths from `<host>:<port>`. + +| Route | Destination | +|------------------------------------------------|-----------------------------------------------------------------------------------------| +| `/` | Show home page with general information regarding the database | +| `/search/` | Redirects to `/search/submissions/` | +| `/search/submissions/` | Search & browse submissions | +| `/search/journals/` | Search & browse journals | +| `/search/users/` | Search & browse users | +| `/settings/` | Change default search settings | +| `/user/<username>/` | Show information regarding a specific user | +| `/user/<username>/icon/` | Redirect to username's icon on Fur Affinity | +| `/user/<username>/thumbnail/` | Redirect to username's icon on Fur Affinity | +| `/gallery/<username>/` | Browse & search a user's gallery submissions | +| `/scraps/<username>/` | Browse & search a user's scraps submissions | +| `/submissions/<username>/` | Browse & search a user's gallery & scraps submissions | +| `/favorites/<username>/` | Browse & search a user's favorite submissions | +| `/mentions/<username>/` | Browse & search the submissions where the user is mentioned | +| `/journals/<username>/` | Browse & search a user's journals | +| `/full/<submission id>/` | Redirect to `/submission/<submission id>/` | +| `/view/<submission id>/` | Redirect to `/submission/<submission id>/` | +| `/submission/<submission id>/` | View a submission | +| `/submission/<submission id>/file/` | Open the first submission file | +| `/submission/<submission id>/file/<n>/` | Open the nth first submission file | +| `/submission/<submission id>/files/` | Download all the submission files as a zip | +| `/submission/<submission id>/files/<n1>-<n2>/` | Download submissions files from index n1 to index n2 (0 indexed inclusive) | +| `/submission/<submission id>/thumbnail/` | Open a submission thumbnail (generated for image submissions if no thumbnail is stored) | +| `/submission/<submission id>/zip/` | Download a submission's file, description, and metadata as a ZIP archive | +| `/journal/<journal id>/` | View a journal | +| `/journal/<journal id>/zip/` | Download a journal's content and metadata as a ZIP archive | + +### JSON API Routes + +The following routes return information as JSON responses. They can be reached with `GET` and `POST` requests, the +former supports sending body fields as URL parameters. + +| Route | Destination | Body | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| `/json/search/<table>/` | Perform a search on the database. The query field in the body uses the same [syntax](#query-language) as the query field in the [search page](#browse--search). | `{query?: str, offset?: int, limit?: int, sort?: str, order?: Union["asc", "desc"]}` | +| `/json/user/<username>` | Get user metadata and total submissions/journals | None | +| `/json/submission/<submission id>` | Get submission metadata and comments | None | +| `/json/journal/<journal id>` | Get journal metadata and comments | None | + +## Pages + +_Note:_ the images used in the following sections were taken using light mode, but all pages also support dark mode. + +### Home + +The home page displays general information about the database and contains links to browse and search pages for the +various tables. + +The information table displays the total number of submissions, journals, and users together with the version of the +database. Clicking on any of the counters open the relevant search & browse page. + +### Browse & Search + +The browse and search pages allow to explore the submissions/journals contained in the database. Searches are performed +case-insensitively using a simple syntax in the form `@field term [[| &] term ...]` which allows logic operators, +parentheses and start/end of field matching, see [Query Language](#query-language) for details. + +Search terms for submissions and journals default to the `any` field if none is used, while the `username` field is used +for users searches. + +The controls at the top of the page allow to query the database and control the visualisation of the results. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-form.png" width="600"> +</div> + +The _Search_ input allows to insert the search query. + +The _Field_ menu allows to insert a specific search field using a simple dropdown menu. + +The _Sort_ and adjacent order menus change the sorting field and order of the search results. Submissions and journals +default to descending ID, while users default to ascending username. + +The _View_ menu allows changing between the (default) grid view to a list (table) view + +The _Search_ button submits the search request using the current query and sorting settings. + +The _Browse_ button resets the current search query and reverts to browse mode (all entries). + +The _FA_ button opens the current search on Fur Affinity, translating the shared search and sorting fields (tags, +author, description, and fileurl/fileext). The button is only available when searching submissions. + +The gear button opens the search settings, the question mark button shows a quick help about the query language. + +Under the search controls are the number of results and current page. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-nav.png" width="400"> +</div> + +Under the results numbers are the page controls. _First_ leads to page 1, _Prev_ leads to the previous page, _Next_ +leads to the next page, and _Last_ leads to the last page. These controls are also available at the bottom of the page. + +In grid view, the results are presented using cards containing the same information as the list view, with the addition +of thumbnails for submissions. When searching for submissions or journals, clicking on the card footer (containing the +date and author) will open the author's page. Submissions with more than one file will display a small counter with the +number of files in the upper right corner of the card. + +<div align="center"> +<img src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-card.png" width="200"> +</div> + +In list view, the results are presented in a table with the most important columns: ID, AUTHOR, DATE, and TITLE ( +submissions and journals); USERNAME, FOLDERS, and ACTIVE (users). On small screens some of these columns are shortened +or removed. + +<div align="center"> +<img src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-list.png" width="800"> +</div> + +#### Compatibility with Fur Affinity Search + +Most Fur Affinity search queries (and links) are fully compatible with the program. + +Except for the _NOT_ (!) operator, which follows different syntax rules, all Fur Affinity search fields are fully +supported: `@lower` (treated as `@author`), `@keywords` (treated as `@tags`), `@message` (treated as `@description`) +, `@title` (treated as `@title`), `@filename` (treated as `@fileurl`). + +#### Query Language + +The query language used for this server is based on and improves the search syntax currently used by the Fur Affinity +website. Its basic elements are: + +* `@<field>` field specifier (e.g. `@title`), all database columns are available as search fields. + See [falocalrepo-database](https://pypi.org/project/falocalrepo-database/) for details on the available columns. +* `()` parentheses, they can be used for better logic operations +* `&` _AND_ logic operator, used between search terms +* `|` _OR_ logic operator, used between search terms +* `!` _NOT_ logic operator, used as prefix of search terms +* `""` quotes, allow searching for literal strings without needing to escape +* `%` match 0 or more characters +* `_` match exactly 1 character +* `^` start of field, when used at the start of a search term, it matches the beginning of the field +* `$` end of field, when used at the end of a search term, it matches the end of the field + +All other strings are considered search terms. + +The search uses the `@any` field by default for submissions and journals, allowing to do general searches without +specifying a field. The `@any` field does not include the `FAVORITE`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` fields and +must be searched manually using the respective query fields. When searching users, `@username` is the default field. + +Search terms that are not separated by a logic operator are considered _AND_ terms (i.e. `a b c` -> `a & b & c`). + +Except for the `ID`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` fields, all search terms are searched through the +whole content of the various fields: i.e. `@description cat` will match any item whose description field contains "cat". +To match items that contain only "cat" (or start with, end with, etc.), the `%`, `_`, `^`, and `$` operators need to be +used (e.g. `@description ^cat`). + +Search terms for `ID`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` are matched exactly as they are: i.e. `@id 1` will match +only items whose ID field is exactly equal to "1", to match items that contain "1" the `%`, `_`, `^`, or `$` operators +need to be used (e.g. `@id %1%`). + +##### Examples + +Search for journals/submissions containing water and either otter, lutrine, or mustelid, or water and either cat or +feline: + +`water ((otter | lutrine | mustelid) | (cat | feline))` + +`@any water & ((otter | lutrine | mustelid) | (cat | feline))` + +Search for journals/submissions containing "cat" or "feline" but neither "mouse" nor "rodent": + +`(cat | feline) !mouse !rodent` + +Search for general-rated submissions uploaded by a user whose name starts with "tom" that contain either "volleyball" +or "volley" and "ball" separated by one character (e.g. "volley-ball") in any field: + +`@rating general @author tom% @any (volleyball | volley_ball)` + +`(volleyball | volley_ball) @rating general @author tom%` + +Search for journals/submissions uploaded in 2020 except for March: + +`@date ^2020 !^2020-03` + +Search for submissions uploaded in March 2021 (meaning the date has to start with `2021-03`) whose tags contain the +exact tag "ball": + +`@date ^2021-03 @tags "|ball|"` + +`@date ^2021-03 @tags \|ball\|` + +Search for journals/submissions where a specific user named "tom" is mentioned: + +`@mentions "|tom|"` + +`@mentions \|tom\|` + +Search for submissions whose only favorite is a user named "alex": + +`@favorite ^\|alex\|$` + +Search for users whose names contain "mark": + +`@username %mark%` + +Search for journals/submissions whose title ends with "100%": + +`@title 100\%$` + +Search for journals/submissions whose title is exactly "cat": + +`@title ^cat$` + +Search for text submissions with PDF files: + +`@type text @fileext pdf` + +### Search Settings + +The search settings page allows modifying the sorting, ordering, and viewing option that are applied by default to the +various searches. Settings can be saved to the database if it is writable, otherwise they are simply saved for the +current session and reset when the program stops. + +Settings values are saved in the `SETTINGS` table with the `SERVER.SEARCH` setting name. + +### User + +The user page shows information about submissions and journals related to a user (gallery, scraps, favorites, mentions, +and journals) and what folders have been set for download. See [falocalrepo](https://pypi.org/project/falocalrepo/) for +more details on this. The user's profile will be displayed if present in the database. + +Clicking on any of the counters opens the relevant results via the search interface, allowing to refine the search +further. + +The _Next_ and _Prev_ buttons move to the respective users in ascending alphabetical order. + +### Submission + +The submission page shows the submission file(s) (if present), the submission metadata, and the description. + +Image, audio, video, and plain text submission files are displayed directly in the page, others (e.g. PDF files) will +display a link to open them. Clicking on image files will enlarge them to fill the width of the screen for easier +viewing. Video files can be enlarged by using the zoom button under them. + +When a submission has two or more files, a toolbar appears below the file section with buttons to switch between the +different files, show the files in a grid view, and enlarge non-image files (text, video, etc.). + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-file-switcher.png" width="200"> +</div> + +The metadata table contains clickable links to the user's page (see [User](#user) for details), tags, category, species, +gender, rating, folder (gallery/scraps), and to user pages of favouring and mentioned users. + +The description is displayed as-is except for user icons, which are replaced by `@username` styled links to avoid +display errors caused by expired icon links. + +Under the metadata table are a number of buttons that allow to access the submission file, open its Fur Affinity +counterpart, and navigate the other submissions from the author. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-submission.png" width="400"> +</div> + +The download _File_ button downloads the submission file (if present). If more than one file is present, then the button +downloads a zip file containing all submission files. + +The download _ZIP_ button generates a ZIP file containing the submission file, submission thumbnail, description HTML, +and metadata and comments in JSON format. + +The _FA_ button opens the submission on Fur Affinity + +The _Next_ and _Prev_ buttons lead to the next more recent and the previous less recent submissions respectively. + +The _Gallery_, _All_, and _Scraps_ buttons open a search page with the user's gallery submissions, scraps and gallery +submissions together, and scraps submissions respectively. + +To view the currently selected submission file when scrolling down the page, the button in the lower right corner can be +used to open the image in a floating overlay that will remain at the top of the page view. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-submission-overlay.png" width="50"> + +The comments to the submission can be found below the description, and can be reached quickly by clicking on the +floating comments button that appears in the lower right corner of the screen if the submission has comments. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-comments-link.png" width="50"> + +Each comment contains the author (with a link to their user page), post date, and links to the comment itself and, if +the comment is a reply, its parent comments. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/comment-card.png" width="400"> +</div> + +The button furthest to the left (arrow pointing up and to the left) links to the first comment in a reply chain. The +middle button (bent arrow pointing to the left) links to the previous comment in the reply chain. The link button +furthest to the right is a link to that specific comment. + +### Journal + +The journal page shows the journal metadata and content. + +The metadata table contains clickable links to the user's page (see [User](#user) for details) and to user pages of +mentioned users. + +Under the metadata table are a number of buttons that allow to download the journal, open its Fur Affinity counterpart, +and navigate the other journals from the same user. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-journal.png" width="400"> +</div> + +The download _ZIP_ button generates a ZIP file containing the journal content HTML and metadata and comments in JSON +format. + +The _FA_ button opens the journal on Fur Affinity + +The _Next_ and _Prev_ buttons lead to the next more recent, and the previous less recent journals respectively. + +The _All_ button opens a search page with all the user's journals. + +The comments to the journal can be found below the journal text, and can be reached quickly by clicking on the floating +comments button that appears in the lower right corner of the screen if the journal has comments. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-comments-link.png" width="50"> + +Each comment contains the author (with a link to their user page), post date, and links to the comment itself and, if +the comment is a reply, its parent comments. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/comment-card.png" width="400"> +</div> + +The button furthest to the left (arrow pointing up and to the left) links to the first comment in a reply chain. The +middle button (bent arrow pointing to the left) links to the previous comment in the reply chain. The link button +furthest to the right is a link to that specific comment. + +### BBCode + +When the database is in BBCode mode a new buttons appears along submission descriptions, journal contents, and user +profiles to switch between the rendered HTML and the BBCode stored in the database. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-bbcode.png" width="120"> +</div> + +_Note:_ the BBCode to HTML conversion is still a work in progress and some content may be rendered incorrectly; please +open +an [issue](https://github.com/FurryCoders/falocalrepo-server/issues) if you encounter any error :) + + +%package -n python3-falocalrepo-server +Summary: Web interface for falocalrepo. +Provides: python-falocalrepo-server +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-falocalrepo-server +<div align="center"> + +<img alt="logo" width="400" src="https://raw.githubusercontent.com/FurryCoders/Logos/main/logos/falocalrepo-server-transparent.png"> + +# FALocalRepo-Server + +Web interface for [falocalrepo](https://pypi.org/project/falocalrepo/). + +[](https://github.com/FurryCoders/falocalrepo-server) +[](https://pypi.org/project/falocalrepo-server/) +[](https://www.python.org) +[](https://getbootstrap.com) + +</div> + +## Installation & Requirements + +To install the program it is sufficient to use Python pip and get the package `falocalrepo-server`. + +```shell +pip install falocalrepo-server +``` + +Python 3.10 or above is needed to run this program, all other dependencies are handled by pip during installation. For +information on how to install Python on your computer, refer to the official +website [Python.org](https://www.python.org/). + +For the program to run, a properly formatted database created by falocalrepo needs to be present in the same folder. + +The styling is based on the [Boostrap CSS framework](https://getbootstrap.com). + +_Note:_ When upgrading to a new version the styling may be broken to due to the browser using the old stylesheet in its +cache. To fix it, simply delete the browser cache to fetch the new version.f + +## Usage + +``` +falocalrepo-server <database> [--host HOST] [--port PORT] [--ssl-cert SSL_CERT] [--ssl-key SSL_KEY] + [--redirect-http REDIRECT_PORT] [--auth <username>:<password>] [--precache] [--no-browser] +``` + +The server needs one argument pointing at the location of a valid [falocalrepo](https://pypi.org/project/falocalrepo/) +database and accepts optional arguments to manually set host, port, and an SSL certificate with key. By default, the +server is run on 0.0.0.0:80 for HTTP (without certificate) and 0.0.0.0:443 for HTTPS (with certificate). + +The `--precache` options can be used to prepare an initial cache of results from the database to speed up searches. + +When the app has finished loading, it automatically opens a browser window. To avoid this, use the `--no-browser` +option. + +### Redirect Mode + +The optional `--redirect-http` argument changes the app mode to redirection. In this mode the app runs a tiny server +that redirects all HTTP requests it receives on `http://HOST:PORT` to `https://HOST:REDIRECT_PORT`. + +_Note:_ In redirect mode the `database` argument is not checked, so a simple `.` is sufficient.<br/> +_Note:_ In redirect mode the app does not operate the database portion of the server. To run in redirect and server +mode, two separate instances of the program are needed. + +Once the server is running the web app can be accessed at the address shown in the terminal. + +### Authentication + +The `--auth` option allows setting up a username and password to access the server using the HTTP Basic authentication +protocol. + +### Arguments + +| Argument | Default | +|-------------------|--------------------------------------------------| +| `database` | None, mandatory argument | +| `--host` | 0.0.0.0 | +| `--port` | 80 if no SSL certificate is given, 443 otherwise | +| `--ssl-cert` | None | +| `--ssl-key` | None | +| `--redirect-http` | None | +| `--auth` | None | +| `--precache` | False | +| `--no-browser` | True | + +### Examples + +```shell +# Launch an HTTP server reachable from other machines using the server's hostname/IP +falocalrepo-server ~/FA.db +``` + +```shell +# Launch a localhost-only server on port 8080 +falocalrepo-server ~/FA.db --host 127.0.0.1 --port 8080 +``` + +```shell +# Launch a redirect server that listens to port 80 and redirects to port 443 on host 0.0.0.0 +falocalrepo-server . --host 0.0.0.0 --port 80 --redirect-htpp 443 +``` + +```shell +# Launch a server with basic authentication using 'mickey' as username and 'mouse' as password +falocalrepo-server ~/FA.db --auth mickey:mouse +``` + +```shell +# Launch an HTTPS server reachable from other machines using the server's hostname/IP +falocalrepo-server ~/FA.db --ssl-cert ~/FA.certificates/certificate.crt --ssl-key ~/FA.certificates/private.key +``` + +```shell +# Launch a localhost-only HTTPS server on port 8443 +falocalrepo-server ~/FA.db --host 127.0.0.1 --port 8443 --ssl-cert ~/FA.certificates/certificate.crt --ssl-key ~/FA.certificates/private.key +``` + +## Routes + +_Note:_ All the following paths are meant as paths from `<host>:<port>`. + +| Route | Destination | +|------------------------------------------------|-----------------------------------------------------------------------------------------| +| `/` | Show home page with general information regarding the database | +| `/search/` | Redirects to `/search/submissions/` | +| `/search/submissions/` | Search & browse submissions | +| `/search/journals/` | Search & browse journals | +| `/search/users/` | Search & browse users | +| `/settings/` | Change default search settings | +| `/user/<username>/` | Show information regarding a specific user | +| `/user/<username>/icon/` | Redirect to username's icon on Fur Affinity | +| `/user/<username>/thumbnail/` | Redirect to username's icon on Fur Affinity | +| `/gallery/<username>/` | Browse & search a user's gallery submissions | +| `/scraps/<username>/` | Browse & search a user's scraps submissions | +| `/submissions/<username>/` | Browse & search a user's gallery & scraps submissions | +| `/favorites/<username>/` | Browse & search a user's favorite submissions | +| `/mentions/<username>/` | Browse & search the submissions where the user is mentioned | +| `/journals/<username>/` | Browse & search a user's journals | +| `/full/<submission id>/` | Redirect to `/submission/<submission id>/` | +| `/view/<submission id>/` | Redirect to `/submission/<submission id>/` | +| `/submission/<submission id>/` | View a submission | +| `/submission/<submission id>/file/` | Open the first submission file | +| `/submission/<submission id>/file/<n>/` | Open the nth first submission file | +| `/submission/<submission id>/files/` | Download all the submission files as a zip | +| `/submission/<submission id>/files/<n1>-<n2>/` | Download submissions files from index n1 to index n2 (0 indexed inclusive) | +| `/submission/<submission id>/thumbnail/` | Open a submission thumbnail (generated for image submissions if no thumbnail is stored) | +| `/submission/<submission id>/zip/` | Download a submission's file, description, and metadata as a ZIP archive | +| `/journal/<journal id>/` | View a journal | +| `/journal/<journal id>/zip/` | Download a journal's content and metadata as a ZIP archive | + +### JSON API Routes + +The following routes return information as JSON responses. They can be reached with `GET` and `POST` requests, the +former supports sending body fields as URL parameters. + +| Route | Destination | Body | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| `/json/search/<table>/` | Perform a search on the database. The query field in the body uses the same [syntax](#query-language) as the query field in the [search page](#browse--search). | `{query?: str, offset?: int, limit?: int, sort?: str, order?: Union["asc", "desc"]}` | +| `/json/user/<username>` | Get user metadata and total submissions/journals | None | +| `/json/submission/<submission id>` | Get submission metadata and comments | None | +| `/json/journal/<journal id>` | Get journal metadata and comments | None | + +## Pages + +_Note:_ the images used in the following sections were taken using light mode, but all pages also support dark mode. + +### Home + +The home page displays general information about the database and contains links to browse and search pages for the +various tables. + +The information table displays the total number of submissions, journals, and users together with the version of the +database. Clicking on any of the counters open the relevant search & browse page. + +### Browse & Search + +The browse and search pages allow to explore the submissions/journals contained in the database. Searches are performed +case-insensitively using a simple syntax in the form `@field term [[| &] term ...]` which allows logic operators, +parentheses and start/end of field matching, see [Query Language](#query-language) for details. + +Search terms for submissions and journals default to the `any` field if none is used, while the `username` field is used +for users searches. + +The controls at the top of the page allow to query the database and control the visualisation of the results. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-form.png" width="600"> +</div> + +The _Search_ input allows to insert the search query. + +The _Field_ menu allows to insert a specific search field using a simple dropdown menu. + +The _Sort_ and adjacent order menus change the sorting field and order of the search results. Submissions and journals +default to descending ID, while users default to ascending username. + +The _View_ menu allows changing between the (default) grid view to a list (table) view + +The _Search_ button submits the search request using the current query and sorting settings. + +The _Browse_ button resets the current search query and reverts to browse mode (all entries). + +The _FA_ button opens the current search on Fur Affinity, translating the shared search and sorting fields (tags, +author, description, and fileurl/fileext). The button is only available when searching submissions. + +The gear button opens the search settings, the question mark button shows a quick help about the query language. + +Under the search controls are the number of results and current page. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-nav.png" width="400"> +</div> + +Under the results numbers are the page controls. _First_ leads to page 1, _Prev_ leads to the previous page, _Next_ +leads to the next page, and _Last_ leads to the last page. These controls are also available at the bottom of the page. + +In grid view, the results are presented using cards containing the same information as the list view, with the addition +of thumbnails for submissions. When searching for submissions or journals, clicking on the card footer (containing the +date and author) will open the author's page. Submissions with more than one file will display a small counter with the +number of files in the upper right corner of the card. + +<div align="center"> +<img src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-card.png" width="200"> +</div> + +In list view, the results are presented in a table with the most important columns: ID, AUTHOR, DATE, and TITLE ( +submissions and journals); USERNAME, FOLDERS, and ACTIVE (users). On small screens some of these columns are shortened +or removed. + +<div align="center"> +<img src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-list.png" width="800"> +</div> + +#### Compatibility with Fur Affinity Search + +Most Fur Affinity search queries (and links) are fully compatible with the program. + +Except for the _NOT_ (!) operator, which follows different syntax rules, all Fur Affinity search fields are fully +supported: `@lower` (treated as `@author`), `@keywords` (treated as `@tags`), `@message` (treated as `@description`) +, `@title` (treated as `@title`), `@filename` (treated as `@fileurl`). + +#### Query Language + +The query language used for this server is based on and improves the search syntax currently used by the Fur Affinity +website. Its basic elements are: + +* `@<field>` field specifier (e.g. `@title`), all database columns are available as search fields. + See [falocalrepo-database](https://pypi.org/project/falocalrepo-database/) for details on the available columns. +* `()` parentheses, they can be used for better logic operations +* `&` _AND_ logic operator, used between search terms +* `|` _OR_ logic operator, used between search terms +* `!` _NOT_ logic operator, used as prefix of search terms +* `""` quotes, allow searching for literal strings without needing to escape +* `%` match 0 or more characters +* `_` match exactly 1 character +* `^` start of field, when used at the start of a search term, it matches the beginning of the field +* `$` end of field, when used at the end of a search term, it matches the end of the field + +All other strings are considered search terms. + +The search uses the `@any` field by default for submissions and journals, allowing to do general searches without +specifying a field. The `@any` field does not include the `FAVORITE`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` fields and +must be searched manually using the respective query fields. When searching users, `@username` is the default field. + +Search terms that are not separated by a logic operator are considered _AND_ terms (i.e. `a b c` -> `a & b & c`). + +Except for the `ID`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` fields, all search terms are searched through the +whole content of the various fields: i.e. `@description cat` will match any item whose description field contains "cat". +To match items that contain only "cat" (or start with, end with, etc.), the `%`, `_`, `^`, and `$` operators need to be +used (e.g. `@description ^cat`). + +Search terms for `ID`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` are matched exactly as they are: i.e. `@id 1` will match +only items whose ID field is exactly equal to "1", to match items that contain "1" the `%`, `_`, `^`, or `$` operators +need to be used (e.g. `@id %1%`). + +##### Examples + +Search for journals/submissions containing water and either otter, lutrine, or mustelid, or water and either cat or +feline: + +`water ((otter | lutrine | mustelid) | (cat | feline))` + +`@any water & ((otter | lutrine | mustelid) | (cat | feline))` + +Search for journals/submissions containing "cat" or "feline" but neither "mouse" nor "rodent": + +`(cat | feline) !mouse !rodent` + +Search for general-rated submissions uploaded by a user whose name starts with "tom" that contain either "volleyball" +or "volley" and "ball" separated by one character (e.g. "volley-ball") in any field: + +`@rating general @author tom% @any (volleyball | volley_ball)` + +`(volleyball | volley_ball) @rating general @author tom%` + +Search for journals/submissions uploaded in 2020 except for March: + +`@date ^2020 !^2020-03` + +Search for submissions uploaded in March 2021 (meaning the date has to start with `2021-03`) whose tags contain the +exact tag "ball": + +`@date ^2021-03 @tags "|ball|"` + +`@date ^2021-03 @tags \|ball\|` + +Search for journals/submissions where a specific user named "tom" is mentioned: + +`@mentions "|tom|"` + +`@mentions \|tom\|` + +Search for submissions whose only favorite is a user named "alex": + +`@favorite ^\|alex\|$` + +Search for users whose names contain "mark": + +`@username %mark%` + +Search for journals/submissions whose title ends with "100%": + +`@title 100\%$` + +Search for journals/submissions whose title is exactly "cat": + +`@title ^cat$` + +Search for text submissions with PDF files: + +`@type text @fileext pdf` + +### Search Settings + +The search settings page allows modifying the sorting, ordering, and viewing option that are applied by default to the +various searches. Settings can be saved to the database if it is writable, otherwise they are simply saved for the +current session and reset when the program stops. + +Settings values are saved in the `SETTINGS` table with the `SERVER.SEARCH` setting name. + +### User + +The user page shows information about submissions and journals related to a user (gallery, scraps, favorites, mentions, +and journals) and what folders have been set for download. See [falocalrepo](https://pypi.org/project/falocalrepo/) for +more details on this. The user's profile will be displayed if present in the database. + +Clicking on any of the counters opens the relevant results via the search interface, allowing to refine the search +further. + +The _Next_ and _Prev_ buttons move to the respective users in ascending alphabetical order. + +### Submission + +The submission page shows the submission file(s) (if present), the submission metadata, and the description. + +Image, audio, video, and plain text submission files are displayed directly in the page, others (e.g. PDF files) will +display a link to open them. Clicking on image files will enlarge them to fill the width of the screen for easier +viewing. Video files can be enlarged by using the zoom button under them. + +When a submission has two or more files, a toolbar appears below the file section with buttons to switch between the +different files, show the files in a grid view, and enlarge non-image files (text, video, etc.). + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-file-switcher.png" width="200"> +</div> + +The metadata table contains clickable links to the user's page (see [User](#user) for details), tags, category, species, +gender, rating, folder (gallery/scraps), and to user pages of favouring and mentioned users. + +The description is displayed as-is except for user icons, which are replaced by `@username` styled links to avoid +display errors caused by expired icon links. + +Under the metadata table are a number of buttons that allow to access the submission file, open its Fur Affinity +counterpart, and navigate the other submissions from the author. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-submission.png" width="400"> +</div> + +The download _File_ button downloads the submission file (if present). If more than one file is present, then the button +downloads a zip file containing all submission files. + +The download _ZIP_ button generates a ZIP file containing the submission file, submission thumbnail, description HTML, +and metadata and comments in JSON format. + +The _FA_ button opens the submission on Fur Affinity + +The _Next_ and _Prev_ buttons lead to the next more recent and the previous less recent submissions respectively. + +The _Gallery_, _All_, and _Scraps_ buttons open a search page with the user's gallery submissions, scraps and gallery +submissions together, and scraps submissions respectively. + +To view the currently selected submission file when scrolling down the page, the button in the lower right corner can be +used to open the image in a floating overlay that will remain at the top of the page view. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-submission-overlay.png" width="50"> + +The comments to the submission can be found below the description, and can be reached quickly by clicking on the +floating comments button that appears in the lower right corner of the screen if the submission has comments. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-comments-link.png" width="50"> + +Each comment contains the author (with a link to their user page), post date, and links to the comment itself and, if +the comment is a reply, its parent comments. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/comment-card.png" width="400"> +</div> + +The button furthest to the left (arrow pointing up and to the left) links to the first comment in a reply chain. The +middle button (bent arrow pointing to the left) links to the previous comment in the reply chain. The link button +furthest to the right is a link to that specific comment. + +### Journal + +The journal page shows the journal metadata and content. + +The metadata table contains clickable links to the user's page (see [User](#user) for details) and to user pages of +mentioned users. + +Under the metadata table are a number of buttons that allow to download the journal, open its Fur Affinity counterpart, +and navigate the other journals from the same user. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-journal.png" width="400"> +</div> + +The download _ZIP_ button generates a ZIP file containing the journal content HTML and metadata and comments in JSON +format. + +The _FA_ button opens the journal on Fur Affinity + +The _Next_ and _Prev_ buttons lead to the next more recent, and the previous less recent journals respectively. + +The _All_ button opens a search page with all the user's journals. + +The comments to the journal can be found below the journal text, and can be reached quickly by clicking on the floating +comments button that appears in the lower right corner of the screen if the journal has comments. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-comments-link.png" width="50"> + +Each comment contains the author (with a link to their user page), post date, and links to the comment itself and, if +the comment is a reply, its parent comments. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/comment-card.png" width="400"> +</div> + +The button furthest to the left (arrow pointing up and to the left) links to the first comment in a reply chain. The +middle button (bent arrow pointing to the left) links to the previous comment in the reply chain. The link button +furthest to the right is a link to that specific comment. + +### BBCode + +When the database is in BBCode mode a new buttons appears along submission descriptions, journal contents, and user +profiles to switch between the rendered HTML and the BBCode stored in the database. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-bbcode.png" width="120"> +</div> + +_Note:_ the BBCode to HTML conversion is still a work in progress and some content may be rendered incorrectly; please +open +an [issue](https://github.com/FurryCoders/falocalrepo-server/issues) if you encounter any error :) + + +%package help +Summary: Development documents and examples for falocalrepo-server +Provides: python3-falocalrepo-server-doc +%description help +<div align="center"> + +<img alt="logo" width="400" src="https://raw.githubusercontent.com/FurryCoders/Logos/main/logos/falocalrepo-server-transparent.png"> + +# FALocalRepo-Server + +Web interface for [falocalrepo](https://pypi.org/project/falocalrepo/). + +[](https://github.com/FurryCoders/falocalrepo-server) +[](https://pypi.org/project/falocalrepo-server/) +[](https://www.python.org) +[](https://getbootstrap.com) + +</div> + +## Installation & Requirements + +To install the program it is sufficient to use Python pip and get the package `falocalrepo-server`. + +```shell +pip install falocalrepo-server +``` + +Python 3.10 or above is needed to run this program, all other dependencies are handled by pip during installation. For +information on how to install Python on your computer, refer to the official +website [Python.org](https://www.python.org/). + +For the program to run, a properly formatted database created by falocalrepo needs to be present in the same folder. + +The styling is based on the [Boostrap CSS framework](https://getbootstrap.com). + +_Note:_ When upgrading to a new version the styling may be broken to due to the browser using the old stylesheet in its +cache. To fix it, simply delete the browser cache to fetch the new version.f + +## Usage + +``` +falocalrepo-server <database> [--host HOST] [--port PORT] [--ssl-cert SSL_CERT] [--ssl-key SSL_KEY] + [--redirect-http REDIRECT_PORT] [--auth <username>:<password>] [--precache] [--no-browser] +``` + +The server needs one argument pointing at the location of a valid [falocalrepo](https://pypi.org/project/falocalrepo/) +database and accepts optional arguments to manually set host, port, and an SSL certificate with key. By default, the +server is run on 0.0.0.0:80 for HTTP (without certificate) and 0.0.0.0:443 for HTTPS (with certificate). + +The `--precache` options can be used to prepare an initial cache of results from the database to speed up searches. + +When the app has finished loading, it automatically opens a browser window. To avoid this, use the `--no-browser` +option. + +### Redirect Mode + +The optional `--redirect-http` argument changes the app mode to redirection. In this mode the app runs a tiny server +that redirects all HTTP requests it receives on `http://HOST:PORT` to `https://HOST:REDIRECT_PORT`. + +_Note:_ In redirect mode the `database` argument is not checked, so a simple `.` is sufficient.<br/> +_Note:_ In redirect mode the app does not operate the database portion of the server. To run in redirect and server +mode, two separate instances of the program are needed. + +Once the server is running the web app can be accessed at the address shown in the terminal. + +### Authentication + +The `--auth` option allows setting up a username and password to access the server using the HTTP Basic authentication +protocol. + +### Arguments + +| Argument | Default | +|-------------------|--------------------------------------------------| +| `database` | None, mandatory argument | +| `--host` | 0.0.0.0 | +| `--port` | 80 if no SSL certificate is given, 443 otherwise | +| `--ssl-cert` | None | +| `--ssl-key` | None | +| `--redirect-http` | None | +| `--auth` | None | +| `--precache` | False | +| `--no-browser` | True | + +### Examples + +```shell +# Launch an HTTP server reachable from other machines using the server's hostname/IP +falocalrepo-server ~/FA.db +``` + +```shell +# Launch a localhost-only server on port 8080 +falocalrepo-server ~/FA.db --host 127.0.0.1 --port 8080 +``` + +```shell +# Launch a redirect server that listens to port 80 and redirects to port 443 on host 0.0.0.0 +falocalrepo-server . --host 0.0.0.0 --port 80 --redirect-htpp 443 +``` + +```shell +# Launch a server with basic authentication using 'mickey' as username and 'mouse' as password +falocalrepo-server ~/FA.db --auth mickey:mouse +``` + +```shell +# Launch an HTTPS server reachable from other machines using the server's hostname/IP +falocalrepo-server ~/FA.db --ssl-cert ~/FA.certificates/certificate.crt --ssl-key ~/FA.certificates/private.key +``` + +```shell +# Launch a localhost-only HTTPS server on port 8443 +falocalrepo-server ~/FA.db --host 127.0.0.1 --port 8443 --ssl-cert ~/FA.certificates/certificate.crt --ssl-key ~/FA.certificates/private.key +``` + +## Routes + +_Note:_ All the following paths are meant as paths from `<host>:<port>`. + +| Route | Destination | +|------------------------------------------------|-----------------------------------------------------------------------------------------| +| `/` | Show home page with general information regarding the database | +| `/search/` | Redirects to `/search/submissions/` | +| `/search/submissions/` | Search & browse submissions | +| `/search/journals/` | Search & browse journals | +| `/search/users/` | Search & browse users | +| `/settings/` | Change default search settings | +| `/user/<username>/` | Show information regarding a specific user | +| `/user/<username>/icon/` | Redirect to username's icon on Fur Affinity | +| `/user/<username>/thumbnail/` | Redirect to username's icon on Fur Affinity | +| `/gallery/<username>/` | Browse & search a user's gallery submissions | +| `/scraps/<username>/` | Browse & search a user's scraps submissions | +| `/submissions/<username>/` | Browse & search a user's gallery & scraps submissions | +| `/favorites/<username>/` | Browse & search a user's favorite submissions | +| `/mentions/<username>/` | Browse & search the submissions where the user is mentioned | +| `/journals/<username>/` | Browse & search a user's journals | +| `/full/<submission id>/` | Redirect to `/submission/<submission id>/` | +| `/view/<submission id>/` | Redirect to `/submission/<submission id>/` | +| `/submission/<submission id>/` | View a submission | +| `/submission/<submission id>/file/` | Open the first submission file | +| `/submission/<submission id>/file/<n>/` | Open the nth first submission file | +| `/submission/<submission id>/files/` | Download all the submission files as a zip | +| `/submission/<submission id>/files/<n1>-<n2>/` | Download submissions files from index n1 to index n2 (0 indexed inclusive) | +| `/submission/<submission id>/thumbnail/` | Open a submission thumbnail (generated for image submissions if no thumbnail is stored) | +| `/submission/<submission id>/zip/` | Download a submission's file, description, and metadata as a ZIP archive | +| `/journal/<journal id>/` | View a journal | +| `/journal/<journal id>/zip/` | Download a journal's content and metadata as a ZIP archive | + +### JSON API Routes + +The following routes return information as JSON responses. They can be reached with `GET` and `POST` requests, the +former supports sending body fields as URL parameters. + +| Route | Destination | Body | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| +| `/json/search/<table>/` | Perform a search on the database. The query field in the body uses the same [syntax](#query-language) as the query field in the [search page](#browse--search). | `{query?: str, offset?: int, limit?: int, sort?: str, order?: Union["asc", "desc"]}` | +| `/json/user/<username>` | Get user metadata and total submissions/journals | None | +| `/json/submission/<submission id>` | Get submission metadata and comments | None | +| `/json/journal/<journal id>` | Get journal metadata and comments | None | + +## Pages + +_Note:_ the images used in the following sections were taken using light mode, but all pages also support dark mode. + +### Home + +The home page displays general information about the database and contains links to browse and search pages for the +various tables. + +The information table displays the total number of submissions, journals, and users together with the version of the +database. Clicking on any of the counters open the relevant search & browse page. + +### Browse & Search + +The browse and search pages allow to explore the submissions/journals contained in the database. Searches are performed +case-insensitively using a simple syntax in the form `@field term [[| &] term ...]` which allows logic operators, +parentheses and start/end of field matching, see [Query Language](#query-language) for details. + +Search terms for submissions and journals default to the `any` field if none is used, while the `username` field is used +for users searches. + +The controls at the top of the page allow to query the database and control the visualisation of the results. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-form.png" width="600"> +</div> + +The _Search_ input allows to insert the search query. + +The _Field_ menu allows to insert a specific search field using a simple dropdown menu. + +The _Sort_ and adjacent order menus change the sorting field and order of the search results. Submissions and journals +default to descending ID, while users default to ascending username. + +The _View_ menu allows changing between the (default) grid view to a list (table) view + +The _Search_ button submits the search request using the current query and sorting settings. + +The _Browse_ button resets the current search query and reverts to browse mode (all entries). + +The _FA_ button opens the current search on Fur Affinity, translating the shared search and sorting fields (tags, +author, description, and fileurl/fileext). The button is only available when searching submissions. + +The gear button opens the search settings, the question mark button shows a quick help about the query language. + +Under the search controls are the number of results and current page. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-nav.png" width="400"> +</div> + +Under the results numbers are the page controls. _First_ leads to page 1, _Prev_ leads to the previous page, _Next_ +leads to the next page, and _Last_ leads to the last page. These controls are also available at the bottom of the page. + +In grid view, the results are presented using cards containing the same information as the list view, with the addition +of thumbnails for submissions. When searching for submissions or journals, clicking on the card footer (containing the +date and author) will open the author's page. Submissions with more than one file will display a small counter with the +number of files in the upper right corner of the card. + +<div align="center"> +<img src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-card.png" width="200"> +</div> + +In list view, the results are presented in a table with the most important columns: ID, AUTHOR, DATE, and TITLE ( +submissions and journals); USERNAME, FOLDERS, and ACTIVE (users). On small screens some of these columns are shortened +or removed. + +<div align="center"> +<img src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/search-list.png" width="800"> +</div> + +#### Compatibility with Fur Affinity Search + +Most Fur Affinity search queries (and links) are fully compatible with the program. + +Except for the _NOT_ (!) operator, which follows different syntax rules, all Fur Affinity search fields are fully +supported: `@lower` (treated as `@author`), `@keywords` (treated as `@tags`), `@message` (treated as `@description`) +, `@title` (treated as `@title`), `@filename` (treated as `@fileurl`). + +#### Query Language + +The query language used for this server is based on and improves the search syntax currently used by the Fur Affinity +website. Its basic elements are: + +* `@<field>` field specifier (e.g. `@title`), all database columns are available as search fields. + See [falocalrepo-database](https://pypi.org/project/falocalrepo-database/) for details on the available columns. +* `()` parentheses, they can be used for better logic operations +* `&` _AND_ logic operator, used between search terms +* `|` _OR_ logic operator, used between search terms +* `!` _NOT_ logic operator, used as prefix of search terms +* `""` quotes, allow searching for literal strings without needing to escape +* `%` match 0 or more characters +* `_` match exactly 1 character +* `^` start of field, when used at the start of a search term, it matches the beginning of the field +* `$` end of field, when used at the end of a search term, it matches the end of the field + +All other strings are considered search terms. + +The search uses the `@any` field by default for submissions and journals, allowing to do general searches without +specifying a field. The `@any` field does not include the `FAVORITE`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` fields and +must be searched manually using the respective query fields. When searching users, `@username` is the default field. + +Search terms that are not separated by a logic operator are considered _AND_ terms (i.e. `a b c` -> `a & b & c`). + +Except for the `ID`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` fields, all search terms are searched through the +whole content of the various fields: i.e. `@description cat` will match any item whose description field contains "cat". +To match items that contain only "cat" (or start with, end with, etc.), the `%`, `_`, `^`, and `$` operators need to be +used (e.g. `@description ^cat`). + +Search terms for `ID`, `FILESAVED`, `USERUPDATE`, and `ACTIVE` are matched exactly as they are: i.e. `@id 1` will match +only items whose ID field is exactly equal to "1", to match items that contain "1" the `%`, `_`, `^`, or `$` operators +need to be used (e.g. `@id %1%`). + +##### Examples + +Search for journals/submissions containing water and either otter, lutrine, or mustelid, or water and either cat or +feline: + +`water ((otter | lutrine | mustelid) | (cat | feline))` + +`@any water & ((otter | lutrine | mustelid) | (cat | feline))` + +Search for journals/submissions containing "cat" or "feline" but neither "mouse" nor "rodent": + +`(cat | feline) !mouse !rodent` + +Search for general-rated submissions uploaded by a user whose name starts with "tom" that contain either "volleyball" +or "volley" and "ball" separated by one character (e.g. "volley-ball") in any field: + +`@rating general @author tom% @any (volleyball | volley_ball)` + +`(volleyball | volley_ball) @rating general @author tom%` + +Search for journals/submissions uploaded in 2020 except for March: + +`@date ^2020 !^2020-03` + +Search for submissions uploaded in March 2021 (meaning the date has to start with `2021-03`) whose tags contain the +exact tag "ball": + +`@date ^2021-03 @tags "|ball|"` + +`@date ^2021-03 @tags \|ball\|` + +Search for journals/submissions where a specific user named "tom" is mentioned: + +`@mentions "|tom|"` + +`@mentions \|tom\|` + +Search for submissions whose only favorite is a user named "alex": + +`@favorite ^\|alex\|$` + +Search for users whose names contain "mark": + +`@username %mark%` + +Search for journals/submissions whose title ends with "100%": + +`@title 100\%$` + +Search for journals/submissions whose title is exactly "cat": + +`@title ^cat$` + +Search for text submissions with PDF files: + +`@type text @fileext pdf` + +### Search Settings + +The search settings page allows modifying the sorting, ordering, and viewing option that are applied by default to the +various searches. Settings can be saved to the database if it is writable, otherwise they are simply saved for the +current session and reset when the program stops. + +Settings values are saved in the `SETTINGS` table with the `SERVER.SEARCH` setting name. + +### User + +The user page shows information about submissions and journals related to a user (gallery, scraps, favorites, mentions, +and journals) and what folders have been set for download. See [falocalrepo](https://pypi.org/project/falocalrepo/) for +more details on this. The user's profile will be displayed if present in the database. + +Clicking on any of the counters opens the relevant results via the search interface, allowing to refine the search +further. + +The _Next_ and _Prev_ buttons move to the respective users in ascending alphabetical order. + +### Submission + +The submission page shows the submission file(s) (if present), the submission metadata, and the description. + +Image, audio, video, and plain text submission files are displayed directly in the page, others (e.g. PDF files) will +display a link to open them. Clicking on image files will enlarge them to fill the width of the screen for easier +viewing. Video files can be enlarged by using the zoom button under them. + +When a submission has two or more files, a toolbar appears below the file section with buttons to switch between the +different files, show the files in a grid view, and enlarge non-image files (text, video, etc.). + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-file-switcher.png" width="200"> +</div> + +The metadata table contains clickable links to the user's page (see [User](#user) for details), tags, category, species, +gender, rating, folder (gallery/scraps), and to user pages of favouring and mentioned users. + +The description is displayed as-is except for user icons, which are replaced by `@username` styled links to avoid +display errors caused by expired icon links. + +Under the metadata table are a number of buttons that allow to access the submission file, open its Fur Affinity +counterpart, and navigate the other submissions from the author. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-submission.png" width="400"> +</div> + +The download _File_ button downloads the submission file (if present). If more than one file is present, then the button +downloads a zip file containing all submission files. + +The download _ZIP_ button generates a ZIP file containing the submission file, submission thumbnail, description HTML, +and metadata and comments in JSON format. + +The _FA_ button opens the submission on Fur Affinity + +The _Next_ and _Prev_ buttons lead to the next more recent and the previous less recent submissions respectively. + +The _Gallery_, _All_, and _Scraps_ buttons open a search page with the user's gallery submissions, scraps and gallery +submissions together, and scraps submissions respectively. + +To view the currently selected submission file when scrolling down the page, the button in the lower right corner can be +used to open the image in a floating overlay that will remain at the top of the page view. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-submission-overlay.png" width="50"> + +The comments to the submission can be found below the description, and can be reached quickly by clicking on the +floating comments button that appears in the lower right corner of the screen if the submission has comments. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-comments-link.png" width="50"> + +Each comment contains the author (with a link to their user page), post date, and links to the comment itself and, if +the comment is a reply, its parent comments. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/comment-card.png" width="400"> +</div> + +The button furthest to the left (arrow pointing up and to the left) links to the first comment in a reply chain. The +middle button (bent arrow pointing to the left) links to the previous comment in the reply chain. The link button +furthest to the right is a link to that specific comment. + +### Journal + +The journal page shows the journal metadata and content. + +The metadata table contains clickable links to the user's page (see [User](#user) for details) and to user pages of +mentioned users. + +Under the metadata table are a number of buttons that allow to download the journal, open its Fur Affinity counterpart, +and navigate the other journals from the same user. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-journal.png" width="400"> +</div> + +The download _ZIP_ button generates a ZIP file containing the journal content HTML and metadata and comments in JSON +format. + +The _FA_ button opens the journal on Fur Affinity + +The _Next_ and _Prev_ buttons lead to the next more recent, and the previous less recent journals respectively. + +The _All_ button opens a search page with all the user's journals. + +The comments to the journal can be found below the journal text, and can be reached quickly by clicking on the floating +comments button that appears in the lower right corner of the screen if the journal has comments. + +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-comments-link.png" width="50"> + +Each comment contains the author (with a link to their user page), post date, and links to the comment itself and, if +the comment is a reply, its parent comments. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/comment-card.png" width="400"> +</div> + +The button furthest to the left (arrow pointing up and to the left) links to the first comment in a reply chain. The +middle button (bent arrow pointing to the left) links to the previous comment in the reply chain. The link button +furthest to the right is a link to that specific comment. + +### BBCode + +When the database is in BBCode mode a new buttons appears along submission descriptions, journal contents, and user +profiles to switch between the rendered HTML and the BBCode stored in the database. + +<div align="center"> +<img alt="" src="https://raw.githubusercontent.com/FurryCoders/falocalrepo-server/master/doc/buttons-bbcode.png" width="120"> +</div> + +_Note:_ the BBCode to HTML conversion is still a work in progress and some content may be rendered incorrectly; please +open +an [issue](https://github.com/FurryCoders/falocalrepo-server/issues) if you encounter any error :) + + +%prep +%autosetup -n falocalrepo-server-3.3.3 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-falocalrepo-server -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Fri May 05 2023 Python_Bot <Python_Bot@openeuler.org> - 3.3.3-1 +- Package Spec generated @@ -0,0 +1 @@ +b6fd66a874602d789f1fbc1acbd2f405 falocalrepo_server-3.3.3.tar.gz |