afpy / potodo

This project has moved to an open-source forge: https://git.afpy.org/AFPy/potodo

                   

What is it ?

Potodo, a (almost) flawless TODO/progress listing CLI tool for po files.

Potodo is part of poutils!

Poutils (.po utils) is is a metapackage to easily install usefull Python tools to use with po files and potodo is a part of it! Go check out Poutils to discover the other useful tools for po file related translation!

Installation

pip install potodo

Usage example

usage: potodo [-h] [-p path] [-e path [path ...]] [-a X] [-b X] [-f] [-u API_URL] [-n] [-c] [-j] [--exclude-fuzzy] [--exclude-reserved]
              [--only-reserved] [--show-reservation-dates] [--no-cache] [-i] [-l] [--version] [-v]

List and prettify the po files left to translate.

options:
  -h, --help            show this help message and exit
  -p path, --path path  execute Potodo in path
  -e path [path ...], --exclude path [path ...]
                        gitignore-style patterns to exclude from search.
  -a X, --above X       list all TODOs above given X% completion
  -b X, --below X       list all TODOs below given X% completion
  -f, --only-fuzzy      print only files marked as fuzzys
  -u API_URL, --api-url API_URL
                        API URL to retrieve reservation tickets (https://api.github.com/repos/ORGANISATION/REPOSITORY/issues?state=open or
                        https://git.afpy.org/api/v1/repos/ORGANISATION/REPOSITORY/issues?state=open&type=issues)
  -n, --no-reserved     don't print info about reserved files
  -c, --counts          render list with the count of remaining entries (translate or review) rather than percentage done
  -j, --json            format output as JSON
  --exclude-fuzzy       select only files without fuzzy entries
  --exclude-reserved    select only files that aren't reserved
  --only-reserved       select only only reserved files
  --show-reservation-dates
                        show issue creation dates
  --no-cache            Disables cache (Cache is disabled when files are modified)
  -i, --interactive     Activates the interactive menu
  -l, --matching-files  Suppress normal output; instead print the name of each matching po file from which output would normally have been
                        printed.
  --version             show program's version number and exit
  -v, --verbose         Increases output verbosity

Development setup

Create a virtual environment

python3 -m venv venv

Activate it

source venv/bin/activate

Install the dev requirements

pip install -r requirements-dev.txt

Install the pre-commit hook

pre-commit install

Install potodo in a development version

pip install -e .

Release History

• v0.21.2
  • FIX: Don't miss issues (reservations) to files containing multiple dots. Contributed by @eviau.
• v0.21.0
  • A nice new README
• v0.20.0
  • New exclude behavior with gitignore style matching !
• v0.19.2
  • Dropped cache_args to simplify cache functionality
• v0.19.1
  • Fixed a bug of division by 0
  • Replaced Travis-ci tests with github actions
• v0.19.0
  • Fixed windows support
• v0.17.3
  • Fixed a math error where the completion %age of a folder was wrong
  • Fixes on the .potodoignore file
• v0.17.0
  • Added tests
  • Fixed bug where github would rate limit your IP address
  • Fixed argument errors
  • Added -l --matching-files Which will print the path of files matching your arguments
• v0.16.0
  • Args passed to potodo are now cached as well ! This allows for a better control of what is cached !
  • The ignore file now works as the .gitignore does. Add a venv/ in your .potodoignore for example :)
• v0.15.0
  • Potodo now supports .potodoignore files ! You can finally ignore the venv you made 🎉
• v0.14.3
  • Added cache versioning to avoid errors when cache changes, for example if files are moved between potodo versions.
• v0.14.2
  • Nothing new, just code moved around ! Thanks for sticking around 🎉
• v0.14.1
  • Added --only-reserved option to display only reserved filed
  • Added --reserved-dates to display when a file was reserved
  • Added cache to cache pofiles to speedup the reading process
  • Added logging for verbosity
  • Added interactive option with --interactive
  • Added contributors in the readme
• < v0.14.1
  • Base version

Contributing

1. Fork it (https://github.com/afpy/potdo/fork)
2. Create your feature branch (git checkout -b feature/fooBar

/!\ Don't forget to bump the version in potodo/__init__.py when you're pushing your changes to your branch

3. Commit your changes (git commit -am 'Add some fooBar')
4. Push to the branch (git push origin feature/fooBar)
5. Create a new Pull Request

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Julien Palard 👀 💻

Antoine 👀 💻

Jules Lasne (jlasne) 👀 💻

Christophe Nanteuil 👀 💻

Claire Revillet 👀 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

potodo's Issues

potodo ignores root files

add --version option

Option to show only file that are reserved?

From @JulienPalard

Clarify `print_list`

The print_list list is confusing and needs to be clarified.

A better name, another implementation to know what folder to print ? we'll see

Test issue created from Command line

this is the body

Améliorations JSON

[
        {
            "name": "folder/",
            "percent_translated": 0.0,
            "files": [
                {
                    "name": "folder/file3",
                    "path": "some/path/folder/file3.po",
                    "entries": 1,
                    "fuzzies": 0,
                    "translated": 0,
                    "percent_translated": 0,
                    "reserved_by": null,
                },
            ],
        },
        {
            "name": "python-docs-fr/",
            "percent_translated": 25,
            "files": [
                {
                    "name": "python-docs-fr/file1",
                    "path": "some/path/file1.po",
                    "entries": 3,
                    "fuzzies": 1,
                    "translated": 1,
                    "percent_translated": 33,
                    "reserved_by": null,
                },
                {
                    "name": "python-docs-fr/file2",
                    "path": "some/path/file2.po",
                    "entries": 1,
                    "fuzzies": 0,
                    "translated": 0,
                    "percent_translated": 0,
                    "reserved_by": null,
                },
            ],
        },
    ]

Il y a 2-3 trucs à améliorer sur la sortie ;

• on pourrait mettre « / » au lieu de « python-docs-fr » pour désigner le dossier racine ;
• mettre le « percent_translated » du fichier en décimal ;
• enrichir la description du dossier avec « entries », « fuzzies », « translated » aggrégés.

Originally posted by @awecx in #45 (comment)

EDIT 31/12/20, percent_translated sur les dossiers correct.
EDIT 04/01/21, entries », « fuzzies », « translated » aggrégés.

Add json output option

Sort/show by number of lines to translate

Randomize choice

With exclusion parameter for c-api

Idea for a strategy to find the repo from the remote list

Idea for a strategy to find the repo from the remote list:

• List all remotes
• Filter by keeping only the ones targeting github.com
• Hit the first one on the github API (https://api.github.com/repos/{the_repo})
• See if it has a "parent" attribute:
  • it it has one, the good one is the parent, and we have the github URL. no longer need to care about knowing its local name.
  • if it has none, lucky you it's the right one

Demo of finding it indirectly:

$ curl https://api.github.com/repos/seluj78/python-docs-fr | jq .parent.url
"https://api.github.com/repos/python/python-docs-fr"

Or demo of lucky "it was the right one so it has no parent":

$ curl https://api.github.com/repos/python/python-docs-fr | jq .parent.url
null

Originally posted by @JulienPalard in #37 (comment)

Add a cache option

Cache would be stored in like ~/.potodo/cache.json, and it would contain the last refresh date and refresh every month or something ? The reservations would still be updated everytime the command is ran

[0.2.1] -c isn't recognised by argparse

Also relevant for #21

Github reservations: Support PR titles and multiple files per PR

do not report fuzzies located in commented blocks

Currently all fuzzies are reported, even those located in commented blocks of outdated translation. That would be great if they were not reported

Move from travis to github actions

Setup action to publish on twine when released on GH

Dependabot couldn't authenticate with https://pypi.python.org/simple/

Dependabot couldn't authenticate with https://pypi.python.org/simple/.

You can provide authentication details in your Dependabot dashboard by clicking into the account menu (in the top right) and selecting 'Config variables'.

View the update logs.

Option to show the reservation date?

From @JulienPalard

potodo fails on divide by 0

If you run potodo in the potodo folder, you get a divide by 0 error

Potodo cannot be executed with github enabled remotely

(python-docs-i18n) ➜  ~ potodo -p Projects/python-docs-fr
Traceback (most recent call last):
  File "/Users/seluj78/.venvs/python-docs-i18n/bin/potodo", line 8, in <module>
    sys.exit(main())
  File "/Users/seluj78/.venvs/python-docs-i18n/lib/python3.7/site-packages/potodo/potodo.py", line 232, in main
    args.no_reserved,
  File "/Users/seluj78/.venvs/python-docs-i18n/lib/python3.7/site-packages/potodo/potodo.py", line 78, in exec_potodo
    issue_reservations = get_gh_issue_reservation()
  File "/Users/seluj78/.venvs/python-docs-i18n/lib/python3.7/site-packages/potodo/potodo.py", line 21, in get_gh_issue_reservation
    issues = requests.get("https://api.github.com/repos/" + get_repo_name() + "/issues").json()
  File "/Users/seluj78/.venvs/python-docs-i18n/lib/python3.7/site-packages/potodo/_github.py", line 14, in get_repo_name
    repo_url: str = get_repo_url()
  File "/Users/seluj78/.venvs/python-docs-i18n/lib/python3.7/site-packages/potodo/_github.py", line 9, in get_repo_url
    raise ValueError(f"Unknown error. `git get-url --all upstream|origin` returned {url}")
ValueError: Unknown error. `git get-url --all upstream|origin` returned fatal: not a git repository (or any of the parent directories): .git
(python-docs-i18n) ➜  ~

do not use f-string

Some of our translator still have python 3.5 and then can't use polib. If you don't feel like to do it, I can do it. If so, assign it to me

Replace all string file paths into `Path` objects.

Edited

_Originally posted by @JulienPalard in https://github.com/Seluj78/Potodo/pull/48/files#r366526201

Non tu ne semble pas avoir raté grand chose. C'est juste dommage de les transformer en str après, probablement un souci de compat python 3.5 ou 3.6 j'imagine. => we're dropping support for 3.5

Il faudrait tenter de faire l'effort contraire dans une autre PR peut être : la garder en Path le plus loin possible. Typique cette str est re-transformé en Path dans pofile.py a la ligne 60.

Add travis cache to speedup tox

false classifiers in setup.py

setup.py has classissifier python3.5but this can't be true since the code includes f-strings. So that classifier should be removed. Does potodo run on Python 3.6 ?

Add option to show only files that aren't reserved

Add a way to reserve a .po file from the CLI

That would be great to create the issue from the CLI.

Add default values ?

https://github.com/Seluj78/Potodo/blob/86cb4b86b22b29c5b285868b7a4487b427bd3be4/potodo/potodo.py#L67-L83

Handle arguments passed in the cache to invalidate it if arguments changed

Option to order by reservation dates?

From @JulienPalard

Reinstate -l --matched-files

On #23 it was commented out as it was producing a weird bug

Math error

Using the repository: https://github.com/raulcd/python-docs-es
And the command: potodo --offline --path c-api/
I find strange results in c-api:

# c-api (47.03% done)

- abstract.po                      3 /   3 (100.0% translated)
- allocation.po                    9 /   9 (100.0% translated)
- apiabiversion.po                22 /  22 (100.0% translated)
- arg.po                           0 / 192 (  0.0% translated)
- bool.po                          8 /   8 (100.0% translated)
- buffer.po                        0 / 102 (  0.0% translated)
- bytearray.po                    17 /  17 (100.0% translated)
- bytes.po                         0 /  60 (  0.0% translated)
- capsule.po                       0 /  29 (  0.0% translated)
- cell.po                         10 /  10 (100.0% translated)
- code.po                          9 /   9 (100.0% translated)
- codec.po                         0 /  27 (  0.0% translated)
- complex.po                       0 /  25 (  0.0% translated)
- concrete.po                     11 /  11 (100.0% translated)
- contextvars.po                   0 /  31 (  0.0% translated)
- conversion.po                   22 /  27 ( 81.0% translated), 5 fuzzy
- coro.po                          0 /   6 (  0.0% translated)
- datetime.po                      0 /  41 (  0.0% translated)
- descriptor.po                    4 /   4 (100.0% translated)
- dict.po                          0 /  31 (  0.0% translated)
- exceptions.po                    0 / 261 (  0.0% translated)
- file.po                          0 /  15 (  0.0% translated)
- float.po                        14 /  14 (100.0% translated)
- function.po                     18 /  18 (100.0% translated)
- gcsupport.po                     0 /  25 (  0.0% translated)
- gen.po                           8 /   8 (100.0% translated)
- import.po                        0 /  44 (  0.0% translated)
- index.po                         2 /   2 (100.0% translated)
- init.po                          0 / 287 (  0.0% translated)
- init_config.po                   0 / 274 (  0.0% translated)
- intro.po                         0 /  92 (  0.0% translated)
- iter.po                          5 /   5 (100.0% translated)
- iterator.po                      8 /   8 (100.0% translated)
- list.po                          0 /  23 (  0.0% translated)
- long.po                          0 /  52 (  0.0% translated)
- mapping.po                      15 /  15 (100.0% translated)
- marshal.po                      15 /  15 (100.0% translated)
- memory.po                        0 / 150 (  0.0% translated)
- memoryview.po                    8 /   9 ( 88.0% translated), 1 fuzzy
- method.po                       17 /  17 (100.0% translated)
- module.po                        0 /  87 (  0.0% translated)
- none.po                          4 /   4 (100.0% translated)
- number.po                        0 /  41 (  0.0% translated)
- objbuffer.po                     8 /   8 (100.0% translated)
- object.po                        0 /  77 (  0.0% translated)
- objimpl.po                       2 /   2 (100.0% translated)
- refcounting.po                  11 /  11 (100.0% translated)
- reflection.po                    8 /   8 (100.0% translated)
- sequence.po                      0 /  27 (  0.0% translated)
- set.po                           0 /  23 (  0.0% translated)
- slice.po                         0 /  20 (  0.0% translated)
- stable.po                        6 /   6 (100.0% translated)
- structures.po                    0 / 112 (  0.0% translated)
- sys.po                           0 /  69 (  0.0% translated)
- tuple.po                         0 /  48 (  0.0% translated)
- type.po                          0 /  52 (  0.0% translated)
- typeobj.po                       0 / 586 (  0.0% translated)
- unicode.po                       0 / 332 (  0.0% translated)
- utilities.po                     2 /   2 (100.0% translated)
- veryhigh.po                     61 /  61 (100.0% translated)
- weakref.po                      10 /  10 (100.0% translated)

(Yes it's a patched version of potodo that displays 100.0% translated lines also, to better see the issue)

It indicates ~47% is done, but visually I don't think so, so I checked and find 9%:

$ potodo --offline --path c-api/ | awk '{done += $3; all += $5} END {print 100 * done / all}'
9.4029

9% makes more sense when we count translated and untranslated entries:

$ msgcat c-api/*.po | msgattrib --translated | grep -c '^msgid'
343
(python-docs-es) mdk@seraph:~/clones/python/python-docs-es (3.8)
$ msgcat c-api/*.po | grep -c '^msgid'
3508

there's 343/3508 entries translated, roughly 10%, so the 9.4% looks right, the 47% looks wrong.

Oh, is it 47% of files done? Maybe not:

$ potodo --offline --path c-api/ | grep -c ^-
61
$ potodo --offline --path c-api/ | grep -c 100.0%
27
$ python3
>>> 100 * 27 / 61
44.26229508196721

Add travis.yml

With black and mypy and pytests with coverage

Add an "exclude" option to skip some directories.

Needed for python/python-docs-fr#1289.

What is cache_args?

I don't understand what this variable is. But it looks a good source of "full caches reset", which looks bad to me.

LC_MESSAGES from venv should not be here

find the culprit, or add a .potodoignore

Add a select of the file you want to translate and url open a new issue

Add no fuzzy option

show no fuzzys

fuzzy / fuzzies in output

Add a switch when adding to the buffer to use plural when there's more than a fuzzy in the file

Refactor code to use classes ?

Files at root level are not taken into account for "reserved" keywords.

For instance, glossary.po does not appear reserved ATM.

Add tests

Add verbose option

--json option does not work

With the following traceback:

Traceback (most recent call last):
  File "/usr/lib/python3.8/runpy.py", line 193, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.8/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/home/antoine/github/Potodo/potodo/__main__.py", line 3, in <module>
    __import__("potodo.potodo").potodo.main()
  File "/home/antoine/github/Potodo/potodo/potodo.py", line 305, in main
    exec_potodo(**vars(args))
TypeError: exec_potodo() got an unexpected keyword argument 'json'

Potodo fails abruptly when no "origin" remote is found.

potodo should look for "upstream" AND "origin". It only checks for "origin".
Worse, looking for a non-existent remote make it fails with a CalledProcessError

Search in the .git files the repo url

Adding contributors

Cache: If only a file has changed, only refresh this one

Fix if issue where PR doesn't have `.po` in title or full path (folder/file.po)

"Refactor" code to pass `mypy --strict`

Potodo is not working on Windows

"NotImplementedError: "Windows" is currently not supported."