Merge development/remastering into master

Author: unsektor

changelog.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+- [ ] feature: implement r/w stream edit using reading by chunks instead of by lines 
+- [ ] enhancement: change dictionary format: better compress
+- [ ] feature: extend dictionary: add more words, handle separately lower/upper-cased specific words
+- [ ] feature: add lint option
+- [ ] feature: add replacement stats
+
+## [0.1.0] — 2025-02-16
+
+`md.language.yofication` package initial version
+
+# Archived versions
+
+<details><summary>archived "yoficator" package versions</summary>
+
 ## 0.1.7 — 2025-02-15
 ### Changed
 
@@ -52,3 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unversioned — 2015-11-17
 
 Initial release
+
+</details>
+
+[0.1.0]: https://github.com/md-py/md.language.yofication/releases/tag/0.1.0

docs/_static/architecture-overview.class-diagram.png

@@ -0,0 +1,61 @@
+@startuml
+
+skinparam class {
+  BackgroundColor #ebebeb
+  ArrowColor      #333
+  BorderColor     #333
+}
+
+skinparam lineType ortho
+
+package md.language.yoficate {
+  interface LoadDictionaryInterface {
+    + load(file_path: str) -> DictionaryType
+    + supports(file_path: str) -> bool
+  }
+
+  interface DictionaryInterface {
+    + find(word: str) -> typing.Optional[str]
+    + has(word: str) -> bool
+  }
+
+  interface YoficateInterface {
+    + text(text: str) -> str
+    + word(word: str) -> str
+  }
+
+  class BytesStreamLoadDictionary {
+    + load(stream: typing.IO[bytes], encoding: str = 'utf-8') -> DictionaryType
+  }
+
+  class TextFileLoadDictionary implements LoadDictionaryInterface {
+    - bytes_stream_load_dictionary: BytesStreamLoadDictionary
+    + load(file_path: str) -> DictionaryType
+    + supports(file_path: str) -> bool
+  }
+
+  class Bz2TextFileLoadDictionary implements LoadDictionaryInterface {
+    - bytes_stream_load_dictionary: BytesStreamLoadDictionary
+    + load(file_path: str) -> DictionaryType
+    + supports(file_path: str) -> bool
+  }
+
+  class MappingDictionary implements DictionaryInterface {
+    - dictionary: DictionaryType
+    + find(word: str) -> typing.Optional[str]
+    + has(word: str) -> bool
+  }
+
+  class RegularExpressionYoficate implements YoficateInterface {
+    - dictionary: DictionaryInterface
+    - e_word_regexp: re.Pattern
+    + text(text: str) -> str
+    + word(word: str) -> str
+  }
+
+  TextFileLoadDictionary *-down-> BytesStreamLoadDictionary
+  Bz2TextFileLoadDictionary *-down-> BytesStreamLoadDictionary
+  RegularExpressionYoficate *-> DictionaryInterface
+}
+
+@enduml

docs/_static/architecture-overview.class-diagram.puml

@@ -0,0 +1,73 @@
+# md.language.yofication
+
+md.language.yofication component provides a cyrillic text yofication (ёфикация) API and CLI application.
+
+This is remastered version of [Yoficator](https://github.com/unabashed/yoficator) 
+originally developed by unabashed.
+
+## Architecure overview
+
+[![architecture overview class diagram](_static/architecture-overview.class-diagram.svg)](_static/architecture-overview.class-diagram.svg)
+
+## Component overview
+
+```python3
+# Type
+DictionaryType = typing.Mapping[str, str]
+
+# ... alias to primary implementation
+DefaultYoficate = RegularExpressionYoficate
+
+# ... function to load built-in dictionary
+def get_builtin_dictionary(locale: typing.Literal['ru_RU'] = 'ru_RU') -> MappingDictionary: ...
+```
+
+## Installation
+
+```sh
+pip install md.language.yofication --index https://source.md.land/python/
+```
+
+## Usage
+
+CLI Application provides next options:
+
+- `--no-replace` (DEFAULT) — disables original files modification. Modified content is being printed
+  to standard output (STDOUT). Conflicts with `--replace` option. Makes no sense when few files arguments are specified. 
+- `--replace` — enables original files modifications. Conflicts with `--no-replace` option.
+  Makes no sense when no files arguments were specified.
+
+For more details see program help:
+
+```sh
+python3 -m md.language.yofication -h
+```
+
+Operations with files:
+
+1. Prints the modified text content to standard output (STDOUT) **without changing the file** 
+   (the `--no-replace` option is the default).
+   ```sh
+   python3 -m md.language.yofication ./file.txt  # prints to STDOUT
+   ```
+2. Replaces specified file with yoficated content
+   ```sh
+   python3 -m md.language.yofication --replace ./file.txt  # replace in-place
+   python3 -m md.language.yofication --replace ./file.txt ./file2.txt ./file3.txt  # replaces files
+   find . -type f -iname '*.txt' -exec python3 -m md.language.yofication --replace {} \+  # replaces files
+   ```
+
+Operation standard input (STDIN):
+
+1. Reads text from standard input (STDIN) and writes modified text to standard output (STDOUT).
+   ```sh
+   cat ./file.txt | python3 -m md.language.yofication  # reads from STDIN, prints to STDOUT
+   echo "Где ее книга?" | python3 -m md.language.yofication
+   python3 -m md.language.yofication <<< "Где ее книга?"
+   ```
+2. Interactive mode: 
+   ```
+   $ python3 -m md.language.yofication
+   Где ее книга?
+   Где её книга?
+   ```

docs/_static/architecture-overview.class-diagram.svg

@@ -0,0 +1,2 @@
+from ._yofication import *
+from . import *

docs/index.md

@@ -0,0 +1,131 @@
+import os.path
+import sys
+import argparse
+import typing
+import concurrent.futures
+
+
+import md.language.yofication
+
+__all__ = (
+    'ApplicationEchoLines',
+    'ApplicationReplaceLines',
+    'create_cli_parser',
+    'main',
+)
+
+
+class ApplicationEchoLines:
+    def __init__(self, yoficate: md.language.yofication.YoficateInterface) -> None:
+        self._yoficate = yoficate
+
+    def run(self, input_stream: typing.IO[str]) -> None:
+        try:
+            for line in iter(input_stream):
+                print(self._yoficate.text(text=line.rstrip('\n')))
+        except (KeyboardInterrupt, EOFError):
+            pass
+
+
+class ApplicationReplaceLines:
+    def __init__(self, yoficate: md.language.yofication.YoficateInterface) -> None:
+        self._yoficate = yoficate
+
+    def run(self, file_path_list: typing.List[str]) -> None:
+        with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+            for file_path in file_path_list:
+                executor.submit(self._replace_file, file_path=file_path)
+
+    def _replace_file(self, file_path: str) -> None:
+        directory, filename = os.path.split(file_path)
+
+        with open(file_path) as source_stream, open(f'{directory}/.tmp.{filename}', 'w') as destination_stream:
+            for line in source_stream:
+                destination_stream.write(self._yoficate.text(text=line))
+
+        os.rename(file_path, f'{directory}/{filename}.bak.before-yofication')
+        os.rename(f'{directory}/.tmp.{filename}', file_path)
+        os.remove(f'{directory}/{filename}.bak.before-yofication')
+
+
+def create_cli_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='md.language.yofication',
+        description='Yofication program replaces cyrillic letter "е" with letter "ё" in word where it should be.',
+    )
+    parser.add_argument('file_path', nargs='*', help='file to yoficate')
+
+    # dictionary_group = parser.add_mutually_exclusive_group()
+    # dictionary_group.add_argument('--locale', action='store', choices=['ru_RU'], default='ru_RU')
+    # dictionary_group.add_argument('--dictionary', action='store', default=None)
+
+    replace_group = parser.add_mutually_exclusive_group()
+    replace_group.add_argument(
+        '--replace',
+        action='store_true',
+        default=False,
+        help='Replaces files with yoficated content'
+    )
+    replace_group.add_argument(
+        '--no-replace',
+        action='store_true',
+        default=True,
+        help=(
+            'DEFAULT: Prints yoficated file content instead of replace. '
+            'Exits with error, if few `file_path` arguments passed.'
+        )
+    )
+    return parser
+
+
+def main(arguments: typing.Sequence[str]) -> int:
+    # | FILES | REPLACE | RESULT            |
+    # |-------|---------|-------------------|
+    # | =0    | 0       | OK (STDIN/STDOUT) |
+    # | =0    | 1       | ERROR             |
+    # | =1    | 0       | OK (STDOUT)       |
+    # | =1    | 1       | OK (REPLACE)      |
+    # | >1    | 0       | ERROR             |
+    # | >1    | 1       | OK (REPLACE)      |
+
+    parser = create_cli_parser()
+    parsed_arguments = parser.parse_args(arguments)
+    locale: typing.Literal['ru_RU'] = 'ru_RU'  # todo add support in further versions
+
+    file_path_count = len(parsed_arguments.file_path)
+
+    # validate
+    if parsed_arguments.replace:
+        if file_path_count == 0:
+            print('Error: no files specified to replace', file=sys.stderr)
+            return 1
+    else:
+        if file_path_count > 1:
+            print('Error: using `--no-replace` option with many files makes no sense', file=sys.stderr)
+            return 1
+
+    # act
+    builtin_dictionary = md.language.yofication.get_builtin_dictionary(locale=locale)
+    yoficate = md.language.yofication.DefaultYoficate(dictionary=builtin_dictionary)
+
+    if not parsed_arguments.replace:
+        # todo consider to separate to `--interactive/-i` and `-`$
+        application = ApplicationEchoLines(yoficate=yoficate)
+        if file_path_count == 0:
+            application.run(input_stream=sys.stdin)
+            return 0
+
+        assert file_path_count == 1
+        with open(parsed_arguments.file_path[0], 'r') as stream:
+            application.run(input_stream=stream)
+        return 0
+
+    assert parsed_arguments.replace and file_path_count >= 1
+    application = ApplicationReplaceLines(yoficate=yoficate)
+    application.run(file_path_list=parsed_arguments.file_path)
+    return 0
+
+
+if __name__ == '__main__':
+    exit_code = main(sys.argv[1:])
+    exit(exit_code)