Skip to content

Consider creating a semver package #169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
2 tasks
tomschr opened this issue Oct 13, 2019 · 8 comments
Closed
2 tasks

Consider creating a semver package #169

tomschr opened this issue Oct 13, 2019 · 8 comments
Assignees
@tomschr
Labels
Release_3.x.y Only for the major release 3

Comments

@tomschr
Copy link
Member

tomschr commented Oct 13, 2019 •
edited
Loading

Definitions

  • Module
    A module is a file containing Python definitions and statements.
  • Package
    A package is a collection of modules in directories that give a package hierarchy.

Situation

The current semver.py module contains almost 800 lines of code. As new functionality is added, the files grows bigger and bigger.

Suggested Solution

Should we consider to refactor the semver module into a package?

If yes, this is a feature which we should introduce for the upcoming 3.0.0 release. Could we label that in GitHub as such (or create a milestone)? 😉

Maybe we should also consider to refactor our test cases too and move them to a tests/ directory and create different files? They are currently almost 700 lines of code.

That issue involves the following actions:

  • refactor semver module into package
  • Probably introduce a tests/ directory?
semver/
├── __main__.py  # basically imports semver.cli.main and runs main()
├── __init__.py  # should contain only the usual constants like __version__, __author__ etc.
├── cli.py       # implements the command line interface
└── [... probably more files ...]

An example (although a bit outdated now as new commits arrived in master) can be viewed in
my fork). It's not perfect, but a start.

Pros

  • Make files smaller and more readable
  • No API change to the user
  • Easier to add more functionality
  • With __main__.py, it is possible to use python -m semver -h

Cons

  • More files means also, to search where a function is defined
  • Slightly more difficult to test as it may be needed to run tox first or create a virtual environment.

What do you think? 😉
@s-celles
Copy link
Member

+1 as it will also reduce the possibility of having conflicts.

But maybe we should consider this for a 3.0.0 release

@s-celles s-celles added the Release_3.x.y Only for the major release 3 label Oct 14, 2019
@tomschr tomschr self-assigned this Apr 20, 2020
@tlaferriere
Copy link
Contributor

I believe that the pros here really outweigh the cons:

  • More files means also, to search where a function is defined

A well named file will contain relevant functions, therefore narrows down where you could possibly find a function related to a specific feature.
As for the edge cases, that's what IDEs are for, right? 😜

  • Slightly more difficult to test as it may be needed to run tox first or create a virtual environment.

Relative imports still work when breaking up a module into a package.
Also, once the config is written and just works, you probably will never touch it again.

I would give this a +2 if I could since the semver.py file is starting to bloat with some mutually irrelevant functionalities (not irrelevant to the package, mind you, to each other only).

@tlaferriere
Copy link
Contributor

Probably introduce a tests/ directory?

That is an interesting question 🤔 ...

From my personal experience, most python packages I've worked with tend to have a tests directory that mirrors the package they are testing.
OTOH, I've enjoyed working with frameworks (like Angular, to name one) that have the test module in the same directory as the module they are testing, as it brings the tests closer to the code, and I've read in many python testing frameworks that they support discovering tests pretty much anywhere, referring to this kind of organisation.

Out of familiarity, I would be tempted to go with the former for the usual pro: it is easier to exclude test code collecting files for packaging.

@tomschr
Copy link
Member Author

tomschr commented Jun 10, 2020

I believe that the pros here really outweigh the cons:

  • More files means also, to search where a function is defined

A well named file will contain relevant functions, therefore narrows down where you could possibly find a function related to a specific feature.
As for the edge cases, that's what IDEs are for, right?

In theory yes. But not everybody uses IDEs.

  • Slightly more difficult to test as it may be needed to run tox first or create a virtual environment.

Relative imports still work when breaking up a module into a package.
Also, once the config is written and just works, you probably will never touch it again.

Right.

I would give this a +2 if I could since the semver.py file is starting to bloat with some mutually irrelevant functionalities (not irrelevant to the package, mind you, to each other only).

Yes, that would probably help to focus and consolidate.

@tomschr
Copy link
Member Author

tomschr commented Jun 10, 2020

Probably introduce a tests/ directory?

That is an interesting question ...

From my personal experience, most python packages I've worked with tend to have a tests directory that mirrors the package they are testing.
OTOH, I've enjoyed working with frameworks (like Angular, to name one) that have the test module in the same directory as the module they are testing, as it brings the tests closer to the code, and I've read in many python testing frameworks that they support discovering tests pretty much anywhere, referring to this kind of organisation.

You are right, test frameworks can discover tests almost anywhere. From a technical side, it doesn't matter where they are. It's probably a matter of taste.

Out of familiarity, I would be tempted to go with the former for the usual pro: it is easier to exclude test code collecting files for packaging.

Exactly. I prefer a separate tests/ directory as I believe, it shouldn't be installed with the code. It's a method to help developers, but for users it's pretty useless.

@tlaferriere
Copy link
Contributor

Looking at the current direction the project is taking, I think we will have 2 files:

  • version_info.py: contains the VersionInfo class
  • cli.py: contains all the functions used for the cli.

Seeing that most module level functions are now being deprecated, I think this layout will be clear and it shouldn't be too hard to search for a functionality.

@tomschr
Copy link
Member Author

tomschr commented Jun 16, 2020 •
edited
Loading

[...] I think we will have 2 files:

Depends how we count it. 😉 If we count the __init__.py and __main__.py files too, it would be four.

Seeing that most module level functions are now being deprecated, I think this layout will be clear and it shouldn't be too hard to search for a functionality.

Yes, I think so too. If it turns out we should keep one or two module level functions, we could create a third file.

@tlaferriere tlaferriere mentioned this issue Oct 23, 2020
Closed
@tomschr tomschr mentioned this issue Oct 26, 2020
Closed
@tlaferriere tlaferriere mentioned this issue Oct 26, 2020
Closed
@tomschr
Copy link
Member Author

tomschr commented Nov 1, 2020

This is now integrated in #306

@tomschr tomschr closed this as completed Nov 1, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@tomschr tomschr

Labels
Release_3.x.y Only for the major release 3
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Create semver package tlaferriere/python-semver
3 participants
@s-celles @tomschr @tlaferriere