Package: pyjami
Python-basedJava codemigration helper (Pyjami)Python library which helps to automate the migration of Java classes/enums/interfaces.ScenarioWhen would you want to use this?You have a Java project. You want to migrate 99+ classes/enums/interfaces in it. Let's say it contains acom.foo.bar.MyClass, and you want to replace all its usages with those oforg.example.newPackage.MyClass.Your first instinct is afind-and-replace, but you'd have to deal withwildcard importsand partially-qualified references at each level of the package.You thought ofIntelliJ IDEA. It offers aRefactor>Migrate Packages and Classesfeature, but:You have a morecomplicated mappingto specify. Perhaps you want to migratelorem.Footoipsum.Foo, but forlorem.Bar, you want to migrate it todolor.Bar. To do so in IntelliJ IDEA, you'd have to manually punch in each mapping rule.You don't want to migrate all of them inone transaction. Maybe you want to run unit tests after migrating each, committing the changes to a separate revision only if the tests all pass. IntelliJ IDEA doesn't offer such fine-grained control.Or you simply can't use / would avoid IntelliJ IDEA for some reason.That's when this toolkit comes to help.UsageMigrate one symbolPlease ensure that you've installed these executable programs:gnu-sed(installed by default on most Linux distros; a manual step on macOS). This is because the BSD edition ofseddoes not support word boundaries ("\b").ripgrep, a line-oriented search tool that recursively searches the current directory for a regex pattern.To migrate usages ofcom.foo.bar.MyClasstoorg.example.newPackage.MyClass, usemigrate(...)injava_symbol_migration_helpers.py:frompathlibimportPathfrompyjami.java_symbol_migration_helpersimportfind_suitable_sed_command,migratemigrate(symbol="MyClass",path="src/main/com/foo/bar",old_package="com.foo.bar",new_package="org.example.newPackage",repo_dir=Path("repo/"),pom_dependency="""<dependency><!-- New home for MyClass. --><groupId>org.example</groupId><artifactId>newPackage</artifactId></dependency>""",sed_executable=find_suitable_sed_command(),)Gather information for a list of symbols to migrateWe provide amake_table()function that gathers information about the symbols that are required in the migration process to follow.Given an iterable (preferably a Pandas Series) of string, each of which being a symbol to migrate, this function returns a Pandas Dataframe with each line indicating the name, the java file path, and the package name of that symbol in the given directory.For example, if you haveMyProject/Lorem.javacontaining:packagecom.example.MyProject;classLorem{...}and you run:make_table(symbols_to_migrate=("Lorem",),search_within_directory=pathlib.Path("MyProject/"),)you will get a table with one row of these values:symbol:Lorempath:MyProject/Lorem.javapackage:com.example.MyProjectThese are the required information to feed intomigrate().In the case that multiple file paths are found for a given symbol, the first file path that is a child of the firstmost entry inorder_of_preferenceis taken. When none is present, it's treated as if no file path is found for this symbol. Therefore, even if you don't have a preference of which directories to favor, you might still want to provideorder_of_preferencewith at least asearch_within_directory, so that at least some choice is taken.Extra -- Sorting Components in an OpenAPI ContractThis is a common scenario to encounter when migrating handwritten Java code to a library generated from OpenAPI contract. In fact, this is the original case that kicked off this project.Therefore, Pyjami also provides tools that specifically help with OpenAPI migrations. For example,sort_components_in_contract.pysorts components (data models) in an OpenAPI contract YAML file topologically, so that you can migrate with confidence.Suppose your OpenAPI contract declares 2 components,PetandPets, withPetsreferencing ("depending on")Pet:openapi:"3.0.0"components:schemas:Pet:type:objectPets:type:arrayitems:$ref:"#/components/schemas/Pet"You can get the optimal order to migrate these symbols usingsort_symbols(...):>>>frompyjami.sort_components_in_contractimportsort_symbols>>>sort_symbols("contract.yaml")("Pet","Pets")This ensures that, by the time you attempt to migrateclass Pets,class Pethas already been migrated. This is particularly useful if you want to ensure that the migration of every single symbol should keep the unit tests intact.DevelopmentThis repository usesPoetryfor managing dependencies and packaging.DocumentationRefer todocs/index.htmlfor documentation. It's also published as GitHub pageshere.Pyjami's documentation is generated via thepdoctool:pdoc./pyjami-o./docsPre-Commit HooksThe hooks are required for the team. Although skipping this step does not prevent you from making a commit, this step is critical in maintaining a uniform coding style across developers.From now on, whenever you make a new commit, you should see logs like this in your terminal:Check Yaml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................PassedIf you seeBlackfailed and modified files:Check Yaml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted path/to/file.py
All done! ✨ 🍰 ✨
1 file reformatted.Thengit addthe auto-modified files and retry yourgit commitcommand.Please report a bug if you do not see such messages.TestingThis project usespytestfor running tests andpytest-covfor collecting test coverage information.To run the tests, run:pytest--cov=pyjamiYou'll see a report like this:---------- coverage: platform darwin, python 3.10.6-final-0 ----------
Name                                      Stmts   Miss  Cover
-------------------------------------------------------------
pyjami/__init__.py                            0      0   100%
pyjami/java_symbol_migration_helpers.py     150     18    88%
pyjami/sort_components_in_contract.py        53      8    85%
-------------------------------------------------------------
TOTAL                                       203     26    87%Then, you can update the coverage badge:coverage-badge-ocoverage.svgReleasingThis library is available as a package on PyPIhere. To release a new version:Bump the version number inpyproject.tomlwith a commit. Please followSemantic Versioning 2.0.0specifications.Create a new release on GitHubhere.A GitHub workflow will be automatically triggered to build & publish this package to PyPI. Till eBay have an official account on PyPI, this action will keep on using aPyPI API Tokenassociated with Ming's personal PyPI account. The Token is stored on this GitHub repository as an Action Secret.LicenseApache 2.0.