Visitar URL original
Consider creating a semver package · Issue #169 · python-semver/python-semver · GitHub
Skip to content

Consider creating a semver package #169

Closed
Closed
Consider creating a semver package#169
Assignees
tomschr
Labels
Release_3.x.yOnly for the major release 3

Description

@tomschr
tomschr
opened on Oct 13, 2019

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? 😉

Activity

  1. s-celles commented on Oct 14, 2019

    @s-celles
    s-celles
    on Oct 14, 2019
    Member

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

    But maybe we should consider this for a 3.0.0 release

  2. s-celles
    added
    Release_3.x.yOnly for the major release 3
    on Oct 14, 2019
  3. tomschr
    self-assigned this
    on Apr 20, 2020

  4. tlaferriere commented on Jun 10, 2020

    @tlaferriere
    tlaferriere
    on Jun 10, 2020
    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).

  5. tlaferriere commented on Jun 10, 2020

    @tlaferriere
    tlaferriere
    on Jun 10, 2020
    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.

  6. tomschr commented on Jun 10, 2020

    @tomschr
    tomschr
    on Jun 10, 2020
    MemberAuthor

    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.

  7. tomschr commented on Jun 10, 2020

    @tomschr
    tomschr
    on Jun 10, 2020
    MemberAuthor

    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.

  8. tlaferriere commented on Jun 16, 2020

    @tlaferriere
    tlaferriere
    on Jun 16, 2020
    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.

  9. tomschr commented on Jun 16, 2020

    @tomschr
    tomschr
    on Jun 16, 2020
    MemberAuthor

    [...] 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.

  10. tomschr commented on Nov 1, 2020

    @tomschr
    tomschr
    on Nov 1, 2020
    MemberAuthor

    This is now integrated in #306

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

Metadata

Metadata

Assignees

Labels

Release_3.x.yOnly for the major release 3

Type

No type

Fields

SIze

None yet

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions