Add Poetry project and documentation to setup a fully standalone working project

.flake8

@@ -0,0 +1,37 @@
+[flake8]
+select = ANN,B,B9,BLK,C,D,E,F,I,S,W
+  # only check selected error codes
+max-complexity = 12
+  # C9 - flake8 McCabe Complexity checker -- threshold
+max-line-length = 120
+  # E501 - flake8 -- line length too long, actually handled by black
+extend-ignore =
+  # E W - flake8 PEP style check
+    E203,E402,E501,W503,  # whitespace, import, line length, binary operator line breaks
+  # S - flake8-bandit safety check
+    S101,S311,S105,  # assert removed in bytecode, pRNG not secure, hardcoded password
+  # ANN - flake8-annotations type annotation check
+    ANN,ANN002,ANN003,ANN101,ANN102,ANN202,  # ignore all for now, but always ignore some
+  # D1 - flake8-docstrings docstring style check
+    D100,D102,D103,D104,D105,  # missing docstrings
+  # D2 D4 - flake8-docstrings docstring style check
+    D200,D205,D400,D401,  # whitespace issues and first line content
+  # DAR - flake8-darglint docstring correctness check
+    DAR103,  # mismatched or missing type in docstring
+application-import-names = app_gradio,text_recognizer,tests,training
+  # flake8-import-order: which names are first party?
+import-order-style = google
+  # flake8-import-order: which import order style guide do we use?
+docstring-convention = numpy
+  # flake8-docstrings: which docstring style guide do we use?
+strictness = short
+  # darglint: how "strict" are we with docstring completeness?
+docstring-style = numpy
+  # darglint: which docstring style guide do we use?
+suppress-none-returning = true
+  # flake8-annotations: do we allow un-annotated Nones in returns?
+mypy-init-return = true
+  # flake8-annotations: do we allow init to have no return annotation?
+per-file-ignores =
+  # list of case-by-case ignores, see files for details
+  */__init__.py:F401,I

.gitignore

@@ -0,0 +1,135 @@
+# Mac Files filter
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# VSCode
+.vscode/

README.md

@@ -15,6 +15,8 @@ Check out the configuration reference at https://huggingface.co/docs/hub/spaces-
 
 # Development Instructions
 
+## Clone this project
+
 Go to the directory where you store your `dev` projects (e.g. `dev`)
 
 ```sh
@@ -26,14 +28,199 @@ Clone the app repo from HF spaces:
 git clone https://huggingface.co/spaces/spanish-classifier-tfg/spanish-tweet-classifier
 ```
 
-Then:
+## Python environment management with Pyenv
+
+To avoid the problems of Python versions, lets use the `pyenv` tool.
+
+Before we start, let's go to our $HOME directory:
+```sh
+cd $HOME
+```
+Now you shoud be in your root directory, e.g. `/Users/fperez` (You can check the current directory where you are with the command `pwd`)
+
+Then, let's update `brew` and install `pyenv`
+```sh
+brew update
+brew install pyenv
+```
+
+Then, for the Zsh, execute in the terminal:
+```sh
+echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc
+echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc
+echo 'eval "$(pyenv init -)"' >> ~/.zshrc
+```
+
+Then restart the terminal to allow the previous changes to work!!!
+
+If you executed the previous steps correctly, now you would be able to show all the python available versions at this time with `pyenv` lets execute:
+
+```sh
+pyenv versions
+```
+
+This will show us something like this:
+```
+  system
+  3.6.0
+* anaconda3-4.3.0 (set by /Users/fperez/.python-version)
+```
+
+Let's show the local Python version with `pyenv`, which should be the same shown when executing `python --version`
+```sh
+pyenv local
+```
+This should show your current local active version of Python. In my case shows the Python version corresponding to the * shown above (anaconda3-4.3.0 which corresponds to Python version 3.6.0)
+
+Same applies for the global version:
+```sh
+pyenv global
+```
+
+Let's install a new specific global version. We will use it later in this project with Poetry:
+```sh
+pyenv install 3.9.12
+```
+
+Now the 3.9.12 version of Python should be installed but not set as a default neither as local nor global Python versions yet. Let's check this:
+
+```sh
+pyenv version
+```
+Should still show us the previous version present in your system (the same one as shown above for the `pyenv local`, 3.6.0 in my case).
+
+Let's set 3.9.12 as the default version:
+
+```sh
+pyenv global 3.9.12
+pyenv local 3.9.12
+```
+
+Doing this, sets the global version in the file `~/.pyenv/version` and the local version in `~/.python-version` both to 3.9.12 (you can check the content of these files with `cat ~/.pyenv/version` and `cat `~/.python-version`).
+
+So, now:
+```sh
+python --version
+pyenv version
+```
+should output `3.9.12`
 
+In the same way:
+```sh
+pyenv versions
+```
+should output something similar to:
 ```
-cd spanish-tweet-classifier
+  system
+  3.6.0
+* 3.9.12 (set by /Users/fperez/dev/spanish-tweet-classifier/.python-version)
+  anaconda3-4.3.0
 ```
 
-Open VSCode and improve the project!
+Now the problem with Python versions should be solved in your Mac! If you start a new terminal,
+the `python --version` command should show `3.9.12`. Check it out by opening a new terminal!
 
+Find more info about pyenv [here](https://realpython.com/intro-to-pyenv/)
+
+## Virtual environments with Poetry
+
+Install [poetry](https://python-poetry.org/docs/):
+```sh
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+Add poetry to your PATH env variable:
+```sh
+$HOME/.local/bin
 ```
+```sh
+echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc
+```
+
+Restart the terminal!
+
+When back, let's show the poetry version:
+```sh
+poetry --version
+```
+should show you something like `1.4.0`. Now poetry is working.
+
+### Install dependencies with poetry
+
+Go to the project directory:
+```sh
+cd ~/dev/spanish-tweet-classifier
+```
+
+Activate the shell, which in turn will create a Python virtual environment for the project.
+```
+poetry shell
+```
+
+As the poetry project has been configured to create a virtual environemnt in the project itself (see the contents
+of the `poetry.toml` file), this command will create a `.venv` directory in the root directory of the project.
+
+Install the project dependencies:
+```sh
+poetry install --with dev
+```
+
+All the dependencies for the project will be included in the `.venv` created by the command above.
+
+```sh
+poetry env list
+```
+should show something like:
+```
+.venv (Activated)
+```
+and the command
+```sh
+which python3
+```
+should show something like:;
+```
+/Users/fperez/.pyenv/shims/python3
+```
+
+### VSCode with poetry
+
+Once the project has been configured with the virtual environment, you can use it (and you should) also in VSCode. 
+
+Steps:
+
+1. Close VSCode (just in case you had the project window already open)
+2. In the project directory (e.g. `~/dev/spanish-tweet-classifier`), execute the command:
+```sh
 code .
-```
+```
+
+Then a new window for the project should appear in VSCode. When selecting a Python file it should show in the
+lower right part of the IDE the Python version 3.9.12 and the active virtual environment ('.venv': poetry).
+
+**NOTE:** If the `.venv` virtual enviroment is not activated by default, activate it manually in VSCode using `CMD+Shift+P` and selecting the Python interpreter from the `.venv` directory in the project.
+
+Also if you open a terminal in VSCode, the virtual environment should be detected and something similar to the
+following should appear in the terminal:
+```
+source /Users/fperez/dev/spanish-tweet-classifier/.venv/bin/activate
+```
+
+## Execute the showcase app locally in your laptop!
+
+After all the previous steps have been done, now you should be able to execute the application locally. All the dependencies for this app should be working so:
+
+1. Go to the root directory of the project
+```sh
+cd ~/dev/spanish-tweet-classifier
+```
+2. If you have open a new terminal, be sure that you are in a poetry shell! Otherwise activate it with:
+```sh
+poetry shell
+```
+3. Launch the showcase app with streamlit
+```sh
+poetry run streamlit run showcase_app.py
+```
+4. The previous command should launch a browser windown pointing to [http://localhost:8501](http://localhost:8581) and you should be able to play with the app!
+5. In the terminal, you can stop the local web server started by streamlit pressing `CTRL+C`

poetry.toml

@@ -0,0 +1,3 @@
+[virtualenvs]
+create = true
+in-project = true

pre-commit-config.yaml

@@ -0,0 +1,62 @@
+
+repos:
+  # a set of useful Python-based pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.1.0
+    hooks:
+      # list of definitions and supported hooks: https://pre-commit.com/hooks.html
+      - id: trailing-whitespace      # removes any whitespace at the ends of lines
+      - id: check-toml               # check toml syntax by loading all toml files
+      - id: check-yaml               # check yaml syntax by loading all yaml files
+      - id: check-json               # check-json syntax by loading all json files
+      - id: check-merge-conflict     # check for files with merge conflict strings
+        args: ['--assume-in-merge']  #  and run this check even when not explicitly in a merge
+      - id: check-added-large-files  # check that no "large" files have been added
+        args: ['--maxkb=10240']      #  where large means 10MB+, as in Hugging Face's git server
+      - id: debug-statements         # check for python debug statements (import pdb, breakpoint, etc.)
+      - id: detect-private-key       # checks for private keys (BEGIN X PRIVATE KEY, etc.)
+
+  # sort imports
+  - repo: https://github.com/pycqa/isort
+    rev: 5.10.1
+    hooks:
+      - id: isort
+        name: isort (python)
+
+  # black python autoformatting
+  - repo: https://github.com/psf/black
+    rev: 22.8.0
+    hooks:
+      - id: black
+    # additional configuration of black in pyproject.toml
+
+  # remove unused imports and variables
+  - repo: https://github.com/PyCQA/autoflake
+    rev: v1.5.3
+    hooks:
+    - id: autoflake
+
+  # flake8 python linter with all the fixins
+  - repo: https://github.com/PyCQA/flake8
+    rev: 3.9.2
+    hooks:
+      - id: flake8
+        exclude: ()
+        additional_dependencies: [
+          flake8-annotations, flake8-bandit, flake8-bugbear, flake8-black, flake8-docstrings,
+          flake8-import-order, darglint, mypy, pycodestyle, pydocstyle]
+        args: ["--config", ".flake8"]
+    # additional configuration of flake8 and extensions in .flake8
+
+  # shellcheck-py for linting shell files
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.8.0.4
+    hooks:
+      - id: shellcheck
+
+  # typing with mypy
+  # - repo: https://github.com/pre-commit/mirrors-mypy
+  #   rev: v0.971
+  #   hooks:
+  #     - id: mypy
+  #       exclude: ^tests/

pyproject.toml

@@ -0,0 +1,37 @@
+[tool.poetry]
+name = "spanish-tweet-classifier"
+version = "0.1.0"
+description = "The app to showcase the tweet classifier"
+authors = ["Your Name <[email protected]>"]
+license = "MIT"
+readme = "README.md"
+packages = [{include = "spanish_tweet_classifier"}]
+
+[tool.poetry.dependencies]
+python = "^3.9.8"
+transformers = "^4.26.1"
+openai = "^0.27.2"
+torch = "^1.13.1"
+
+[tool.poetry.group.dev.dependencies]
+streamlit = "^1.20.0"
+black = "^23.1.0"
+flake8 = "^6.0.0"
+mypy = "^1.1.1"
+pytest = "^7.2.2"
+shellcheck-py = "^0.9.0.2"
+isort = "^5.12.0"
+pre-commit = "^3.1.1"
+autoflake = "^2.0.2"
+huggingface-hub = "^0.13.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.isort]
+profile = "black"
+
+[tool.black]
+line-length = 120
+target-version = ["py39"]