configure python package; added readme

.dockerignore

@@ -1,4 +1,9 @@
 *
+# setuptools_scm
+!.git/
+.git/index
 !Pipfile
 !Pipfile.lock
-!location_guessing_telegram_bot.py
+!README.md
+!location_guessing_game_telegram_bot/
+!setup.py

Dockerfile

@@ -6,7 +6,10 @@ ARG SOURCE_DIR_PATH=/location-guessing-game-telegram-bot
 FROM $BASE_IMAGE as build
 
 RUN apt-get update \
-    && apt-get install --no-install-recommends --yes ca-certificates \
+    && apt-get install --no-install-recommends --yes \
+        ca-certificates \
+        git `# setuptools_scm` \
+        jq `# edit Pipfile.lock` \
     && rm -rf /var/lib/apt/lists/* \
     && useradd --create-home build
 
@@ -19,12 +22,18 @@ WORKDIR $SOURCE_DIR_PATH
 ENV PIPENV_CACHE_DIR=/tmp/pipenv-cache \
     PIPENV_VENV_IN_PROJECT=yes-please \
     PATH=/home/build/.local/bin:$PATH
+# `sponge` is not pre-installed
+RUN jq 'del(.default."location-guessing-game-telegram-bot")' Pipfile.lock > Pipfile.lock~ \
+    && mv Pipfile.lock~ Pipfile.lock \
+    && pipenv install --deploy \
+    && rm -rf $PIPENV_CACHE_DIR
+COPY --chown=build . $SOURCE_DIR_PATH
 RUN pipenv install --deploy \
+    && pipenv run location-guessing-game-telegram-bot --help \
     && pipenv graph \
     && pipenv run pip freeze \
-    && rm -rf $PIPENV_CACHE_DIR
-COPY --chown=build . $SOURCE_DIR_PATH
-RUN chmod -cR a+rX .
+    && rm -rf .git/ $PIPENV_CACHE_DIR \
+    && chmod -cR a+rX .
 
 # workaround for broken multi-stage copy
 # > failed to copy files: failed to copy directory: Error processing tar file(exit status 1): Container ID ... cannot be mapped to a host ID
@@ -48,4 +57,4 @@ ARG SOURCE_DIR_PATH
 COPY --from=build $SOURCE_DIR_PATH $SOURCE_DIR_PATH
 ENV PATH=$SOURCE_DIR_PATH/.venv/bin:$PATH
 WORKDIR $SOURCE_DIR_PATH
-CMD ["python", "location_guessing_game_telegram_bot.py"]
+CMD ["location-guessing-game-telegram-bot"]

Pipfile

@@ -4,9 +4,7 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-# >=13.0 telegram.chat.Chat.send_location shortcut
-# https://github.com/python-telegram-bot/python-telegram-bot/commit/fc5844c13da3b3fb20bb2d0bfcdf1efb1a826ba6#diff-2590f2bde47ea3730442f14a3a029ef77d8f2c8f3186cf5edd7e18bcc7243c39R381
-python-telegram-bot = ">=13.0"
+location-guessing-game-telegram-bot = {path = ".", editable = true}
 
 [dev-packages]
 # black requires python>=3.6

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "c37088f160c98b47950a36733ba55f419830e6ac5e9608b9734fc2572219b6bd"
+            "sha256": "0f2a60732f30fd6ceba7215cb24f8b0f75fe93f9488226203a31ab09b3124052"
         },
         "pipfile-spec": 6,
         "requires": {
@@ -84,6 +84,10 @@
             ],
             "version": "==3.4.5"
         },
+        "location-guessing-game-telegram-bot": {
+            "editable": true,
+            "path": "."
+        },
         "pycparser": {
             "hashes": [
                 "sha256:2d475327684562c3a96cc71adf7dc8c4f0565175cf86b6d7a404ff4c771f15f0",
@@ -96,7 +100,6 @@
                 "sha256:12adf52b59d7b23ba26b1f3e25ca95a4f850985ebf08a019bb7fd835c432929b",
                 "sha256:b87cdb2fca2983d4d49287c76ea64f13c5b786260bb742fe9a28334f20e6b2d3"
             ],
-            "index": "pypi",
             "version": "==13.2"
         },
         "pytz": {

README.md

@@ -1,5 +1,43 @@
+# Location Guessing Game Telegram Bot 🏞️ 🌍 📌
+
+Basic [Telegram Bot](https://telegram.org/) Sending Random [Wikimedia Commons](https://commons.wikimedia.org) Photos
+
+## Setup
+
+1. Download a dataset of photos via the [WikiMap API](https://de.wikipedia.org/wiki/Benutzer:DB111/Tools#WikiMap), e.g. via:
+   ```sh
+   wget --restrict-file-names=windows 'https://wikimap.toolforge.org/api.php?cat=Images_with_annotations&lang=de&year=2010-2015&region=49|9|46|18'
+   ```
+2. Generate a bot API token by sending `/newbot` to [BotFather](https://telegram.me/botfather)
+3. Install bot via `pip3 install --user --upgrade location-guessing-game-telegram-bot`
+   (or use [docker](https://docker.io) / [podman](https://podman.io), see below)
+
+## Usage
+
+1. Launch bot: `location-guessing-game-telegram-bot --telegram-token-path file-containing-api-token --wikimap-export-path wikimap-export.json`
+2. Open a chat with the bot in Telegram by searching for the bot name
+   previously sent to [BotFather](https://telegram.me/botfather)
+3. Send `/photo`, wait, and repeat
+4. Optionally add the bot to a group chat.
+
+## Docker / Podman 🐳
+
+Pre-built docker images are available at https://hub.docker.com/r/fphammerle/location-guessing-game-telegram-bot/tags
+
 ```sh
-$ sudo apt-get install --no-install-recommends python3-python-telegram-bot python3-requests
+$ sudo docker run --name location_guessing_game_telegram_bot \
+    -v /file/containing/api-token:/telegram-token:ro -e TELEGRAM_TOKEN_PATH=/telegram-token \
+    -v /wikimap/export.json:/wikimap-export.json:ro -e WIKIMAP_EXPORT_PATH=/wikimap-export.json \
+    --read-only --cap-drop ALL --security-opt no-new-privileges \
+    docker.io/fphammerle/location-guessing-game-telegram-bot:latest
 ```
 
-https://de.wikipedia.org/wiki/Benutzer:DB111/Tools#WikiMap
+Optionally, replace `sudo docker` with `podman`.
+
+Annotation of signed tags `docker/*` contains docker image digests: https://github.com/fphammerle/location-guessing-game-telegram-bot/tags
+
+## Trivia
+
+Why create a Telegram bot instead of web app?
+
+I created this mini game for my family including my grandparents who are comfortable using Telegram.

location_guessing_game_telegram_bot.py → location_guessing_game_telegram_bot/__init__.py

@@ -1,5 +1,3 @@
-#!/usr/bin/env python3
-
 import argparse
 import json
 import logging
@@ -171,7 +169,3 @@ def _main():
     )
     updater.dispatcher.add_handler(telegram.ext.CommandHandler("photo", _photo_command))
     updater.start_polling()
-
-
-if __name__ == "__main__":
-    _main()

pyproject.toml

@@ -0,0 +1,4 @@
+[build-system]
+# https://github.com/pypa/setuptools_scm/tree/v5.0.1#pyprojecttoml-usage
+requires = ["setuptools>=42", "wheel", "setuptools_scm[toml]>=3.4"]
+build-backend = "setuptools.build_meta"

setup.py

@@ -0,0 +1,44 @@
+import pathlib
+
+import setuptools
+
+_REPO_URL = "https://github.com/fphammerle/location-guessing-game-telegram-bot"
+
+setuptools.setup(
+    name="location-guessing-game-telegram-bot",
+    use_scm_version=True,
+    packages=setuptools.find_packages(),
+    description="Basic Telegram Bot Sending Random Wikimedia Commons Photos",
+    long_description=pathlib.Path(__file__).parent.joinpath("README.md").read_text(),
+    long_description_content_type="text/markdown",
+    author="Fabian Peter Hammerle",
+    author_email="fabian+location-guessing@hammerle.me",
+    url=_REPO_URL,
+    project_urls={"Changelog": _REPO_URL + "/blob/master/CHANGELOG.md"},
+    keywords=["bot", "game", "guessing", "location", "photos", "telegram",],
+    classifiers=[
+        # https://pypi.org/classifiers/
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: End Users/Desktop",
+        "Operating System :: OS Independent",
+        "Topic :: Games/Entertainment",
+        # .github/workflows/python.yml TODO
+        # "Programming Language :: Python :: 3.5",
+        # "Programming Language :: Python :: 3.6",
+        # "Programming Language :: Python :: 3.7",
+        # "Programming Language :: Python :: 3.8",
+        # "Programming Language :: Python :: 3.9",
+    ],
+    entry_points={
+        "console_scripts": [
+            "location-guessing-game-telegram-bot = location_guessing_game_telegram_bot:_main",
+        ]
+    },
+    install_requires=[
+        # >=13.0 telegram.chat.Chat.send_location shortcut
+        # https://github.com/python-telegram-bot/python-telegram-bot/commit/fc5844c13da3b3fb20bb2d0bfcdf1efb1a826ba6#diff-2590f2bde47ea3730442f14a3a029ef77d8f2c8f3186cf5edd7e18bcc7243c39R381
+        "python-telegram-bot >= 13.0"
+    ],
+    setup_requires=["setuptools_scm"],
+    # tests_require=["pytest"], TODO
+)