{"id":19657726,"url":"https://github.com/esss/esss_fix_format","last_synced_at":"2025-04-28T19:32:24.468Z","repository":{"id":10490218,"uuid":"63699873","full_name":"ESSS/esss_fix_format","owner":"ESSS","description":"Simple code formatter and pre-commit checker used internally by ESSS","archived":false,"fork":false,"pushed_at":"2024-08-28T19:08:04.000Z","size":260,"stargazers_count":19,"open_issues_count":7,"forks_count":10,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-08-28T20:50:38.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ESSS.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-19T14:17:05.000Z","updated_at":"2024-08-28T19:07:49.000Z","dependencies_parsed_at":"2023-10-17T01:58:17.854Z","dependency_job_id":"6ac21b40-084d-4b91-87c8-a25535aea32d","html_url":"https://github.com/ESSS/esss_fix_format","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fesss_fix_format","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fesss_fix_format/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fesss_fix_format/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ESSS%2Fesss_fix_format/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ESSS","download_url":"https://codeload.github.com/ESSS/esss_fix_format/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224129260,"owners_count":17260591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T15:33:23.830Z","updated_at":"2024-11-11T15:33:24.690Z","avatar_url":"https://github.com/ESSS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"===============================\nesss_fix_format\n===============================\n\nImportant\n---------\n\nSince then we have moved to pre-commit and standard tools, so this tool is no longer being maintained.\n\n.. image:: https://github.com/ESSS/esss_fix_format/workflows/linux/badge.svg\n  :target: https://github.com/ESSS/esss_fix_format/actions?query=workflow%3Alinux\n\n.. image:: https://github.com/ESSS/esss_fix_format/workflows/windows/badge.svg\n  :target: https://github.com/ESSS/esss_fix_format/actions?query=workflow%3Awindows\n\nSimple code formatter and pre-commit checker used internally by ESSS.\n\n* Imports sorted using `isort \u003chttps://pypi.python.org/pypi/isort\u003e`_\n* Trim right spaces\n* Expand tabs\n* Formats Python code using `black \u003chttps://github.com/python/black\u003e`__\n* Formats C++ code using `clang-format \u003chttps://clang.llvm.org/docs/ClangFormat.html\u003e`_ if a ``.clang-format`` file is available\n\n\nInstall\n-------\n\n.. code-block:: sh\n\n    conda install esss_fix_format\n\nNote:\n\nIf executed from the root environment (or another environment) isort will classify modules incorrectly,\nso you should install and run it from the same environment you're using for your project.\n\n\nUsage\n-----\n\nUse ``fix-format`` (or ``ff`` for short) to reorder imports and format source code automatically.\n\n1. To format files and/or directories::\n\n    fix-format \u003cfile1\u003e \u003cdir1\u003e ...\n\n\n2. Format only modified files in Git::\n\n    fix-format --commit\n\n   Or more succinctly::\n\n    ff -c\n\n\n.. _black:\n\nOptions\n-------\n\nOptions for ``fix-format`` are defined in the section ``[tool.esss_fix_format]]`` of a ``pyproject.toml`` file. The\nTOML file should be placed in an ancestor directory of the filenames passed on the command-line.\n\n\nExclude\n^^^^^^^\n\nA list of file name patterns to be excluded from the formatting. Patterns are matched using python ``fnmatch``:\n\n   .. code-block:: toml\n\n    [tool.esss_fix_format]\n    exclude = [\n        \"src/generated/*.py\",\n        \"tmp/*\",\n    ]\n\n\nBlack\n^^^^^\n\nSince version ``4.0.0`` `black \u003chttps://github.com/python/black\u003e`__ is used as the\ncode formatter for Python code.\n\nFor consistentcy, ``fix-format`` requires a ``pyproject.toml`` at the root of your repository (recommended) or project.\n\nIt is suggested to use minimal configuration, usually just line length:\n\n.. code-block:: toml\n\n    [tool.black]\n    line-length = 100\n\nA popular option is also ``skip-string-normalization = true``, which is recommended when migrating from\nother formatter to ``black``.\n\nSee \"Converting master to black\" below for details.\n\nMigrating a project to use fix-format\n-------------------------------------\n\nFollow this steps to re format an entire project and start using the pre-commit hook:\n\n1. You should have ``ff`` available in your environment already:\n\n    .. code-block:: sh\n\n        $ ff --help\n        Usage: ff-script.py [OPTIONS] [FILES_OR_DIRECTORIES]...\n\n          Fixes and checks formatting according to ESSS standards.\n\n        Options:\n          -k, --check   Check if files are correctly formatted.\n          --stdin       Read filenames from stdin (1 per line).\n          -c, --commit  Use modified files from git.\n          --git-hooks   Add git pre-commit hooks to the repo in the current dir.\n          --help        Show this message and exit.\n\n\n2. For each file you don't want imports reordered add ``isort:skipfile`` to the docstring:\n\n    .. code-block:: python\n\n        \"\"\"\n        isort:skip_file\n        \"\"\"\n\n   Commit using ``-n`` to skip the current hook.\n\n3. If there are any sensitive imports in your code which you wouldn't like to ``ff`` to touch, use\n   a comment to prevent ``isort`` from touching it:\n\n    .. code-block:: python\n\n        ConfigurePyroSettings()  # must be called before importing Pyro4\n        import Pyro4  # isort:skip\n\n4. If you want to use ``clang-format`` to format C++ code, you should copy the ``.clang-format``\n   file from ``esss-fix-format`` to the root of your project. This is optional for now in order\n   to allow incremental changes (if this file is not present, the legacy C++ formatter will\n   be used):\n\n    .. code-block:: sh\n\n        $ cd /path/to/repo/root\n        $ curl -O https://raw.githubusercontent.com/ESSS/esss_fix_format/master/.clang-format\n\n5. If you want to use ``black`` to format Python code, add a ``pyproject.toml`` to the root of\n   your repository; an example can be found in \"Converting master to black\" below.\n\n6. Activate your project environment:\n\n    .. code-block:: sh\n\n            $ conda activate myproject-py36\n\n7. Execute:\n\n    .. code-block:: sh\n\n        $ cd /path/to/repo/root\n        $ ff .\n\n   After it completes, make sure there are no problems with the files:\n\n    .. code-block:: sh\n\n        $ ff . --check\n\n   .. note::\n        if the check fails, try running it again; there's a rare\n        `bug in isort \u003chttps://github.com/timothycrosley/isort/issues/460\u003e`_ that might\n        require to run ``ff /path/to/repo/root`` twice.\n\n   Commit:\n\n    .. code-block:: sh\n\n        $ git commit -anm \"Apply fix-format on all files\" --author=\"fix-format \u003cfix-format@esss.com.br\u003e\"\n\n8. Push and run your branch on CI.\n\n9. If all goes well, it's possible to install pre-commit hooks by using ``ff --git-hooks`` so\n   that any commit will be checked locally before commiting.\n\n10. Profit! 💰\n\nMigrating from PyDev formatter to black\n---------------------------------------\n\nMigrating an existing code base from a formatter to another can be a bit of pain. This steps will\nhelp you diminish that pain as much as possible.\n\n\nConverting ``master`` to black\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe first step is converting your ``master`` branch to black.\n\n1. Add a ``pyproject.toml`` project with this contents:\n\n   .. code-block:: toml\n\n      [tool.black]\n      line-length = 100\n      skip-string-normalization = true\n\n2. If your project doesn't have a ``.isort.cfg`` file, create one at the project's *repository*\n   root with the same contents as `the one \u003chttps://github.com/ESSS/esss_fix_format/blob/master/.isort.cfg\u003e`_\n   in the root of this repository.\n\n3. Run the ``upsert-isort-config`` task to update it (it should be run regularly, specially when adding new\n   dependencies to internal projects, known as \"first party\" dependencies); *or*, if the project needs special\n   configurations due to dual package and source modes, add these lines (and do not run ``upsert-isort-config``):\n\n   .. code-block:: ini\n\n      [settings]\n      profile=black\n      no_sections=True\n      force_alphabetical_sort=True\n\n   This will use black-like grouping, and clump imports together regardless if they are standard library,\n   third party, or local. This avoids getting different results if you have a different environment activated,\n   or commiting from an IDE.\n\n4. Commit, and save the commit hash, possible in a task that you created for this conversion:\n\n   .. code-block:: sh\n\n      $ git commit -anm \"Add configuration files for black\"\n\n\n5. Execute on the root of the repository:\n\n   .. code-block:: sh\n\n      $ fix-format .\n\n6. Ensure everything is fine:\n\n   .. code-block:: sh\n\n      $ fix-format --check .\n\n   If you **don't** see any \"reformatting\" messages, it means everything is formatted correctly.\n\n7. Commit and then open a PR:\n\n   .. code-block:: sh\n\n      $ git commit -anm \"Convert source files to black\" --author=\"fix-format \u003cfix-format@esss.com.br\u003e\"\n\n\nPorting an existing branch to black\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nHere we are in the situation where the ``master`` is already blacken, and you want\nto update your branch. There are two ways, and which way generates less conflicts really\ndepends on the contents of the source branch.\n\nmerge -\u003e Fix format\n'''''''''''''''''''\n\n1. Merge with the target branch, resolve any conflicts and then commit normally.\n\n2. Execute ``fix-format`` in the root of your repository:\n\n   .. code-block:: sh\n\n       $ fix-format .\n\n   This should only change the files you have touched in your branch.\n\n3. Commit and push:\n\n   .. code-block:: sh\n\n     $ git commit -anm \"Convert source files to black\" --author=\"fix-format \u003cfix-format@esss.com.br\u003e\"\n\n\nFix format -\u003e merge\n'''''''''''''''''''\n\n1. Cherry-pick the commit you saved earlier on top of your branch.\n\n2. Execute ``fix-format`` in the root of your repository:\n\n   .. code-block:: sh\n\n       $ fix-format .\n\n   (In very large repositories, this will be a problem on Windows because of the command-line size, do it\n   in chunks).\n\n3. Fix any conflicts and then commit:\n\n   .. code-block:: sh\n\n     $ git commit -anm \"Convert source files to black\" --author=\"fix-format \u003cfix-format@esss.com.br\u003e\"\n\n\nDeveloping\n----------\n\nCreate a conda environment (using Python 3 here) and install it in development mode.\n\n**Make sure you have conda configured to use ``conda-forge`` and ``esss`` conda channels.**\n\n.. code-block:: sh\n\n    $ conda install -n base conda-devenv\n    $ conda devenv\n    $ source activate esss-fix-format-py310\n    $ pre-commit install\n    $ pytest\n\nWhen implementing changes, please do it in a separate branch and open a PR.\n\nReleasing\n^^^^^^^^^\n\nThe release is done internally at ESSS using our `conda-recipes` repository.\n\n\nLicense\n-------\n\nLicensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesss%2Fesss_fix_format","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesss%2Fesss_fix_format","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesss%2Fesss_fix_format/lists"}