setup.py for publishing Memacs properly using pip3

[novoid]

Hi,

I've published multiple (simple) tools using Python3 pip. With Memacs, I do feel that my current knowledge and experience with pip is not enough. Can you come up with a setup.py so that I may publish Memacs properly using pip?

The main things that are worrying me:

• How to provide direct access to module (commands)?
• How to properly handle requirements/dependencies? Is the current requirements.txt OK for this?
• My other projects are (mis-)using the pip version scheme like 2018.08.02.1 (YYYY.MM.DD.). Is there a better way to generate version numbers? (I would like to see arguments for a different scheme than calendar-based)

My first approach for a Memacs setup.py is: https://gist.github.com/novoid/8468915f78e68e8d23c68f2e4df892e5

Please do help me here if you do have more experience in packaging Python projects like this!

[novoid]

An up to date version should be available via https://github.com/novoid/Memacs/blob/master/setup.py

[sanzoghenzo]

Hi @novoid, great project! I still have to install it, but I'm planning to do it ASAP. My thoughts from what I've learned in ~5 years of python:

• requirements.txt are good for developers, especially if version are pinned, to reproduce the exact dev environment (or for docker based CI to exploit caching). For a good user experience pip install memacs (if you plan to publish it on pipy) or cloning the repo and doing pip install . is the "right" way, IMO. That means dependencies have to be declared in setup.py or setup.cfg (or pyproject.toml if using poetry - it looks very promising)

• I've seen that in your latest setup.py the entry_point is commented. This is the way to go, and as stated here,

  [each entry point] can optionally specify “extras” that it depends on, that will be added to sys.path when the script is run.

  Then later on the dynamic discovery section

  It can also include a bracketed list of “extras” that are required for the entry point to be used.

  This goes hand in hand with #74: you specify the "extras" in extras_require and use them in the entry_points declaration.

• I'm in favor of Semantic versioning, a widely accepted system for versioning a project. It's the default of npm packages, and many python packages also use this. In a nutshell:

  • the syntax is major.minor.bugfix
  • bugfix is incremented when, well, a bug is fixed
  • minor is incremented for edits or new feature that don't break the API (backward compatible)
  • major is incremented for edits that changes the API, so backward compatibility is not granted.

  I like to use it in conjunction with commitizen and conventional commits, so that version are bumped by parsing the commits messages, and you can also automate it with Actions.

[novoid]

Thanks @sanzoghenzo for your comments!

Unfortunately, my personal pressure is not as high as it should be to distribute memacs via pip since I'm using the sources directly. On the other hand, I'm not sure if the current status should be published via pip because it would require many dependencies considering the wide range of modules. #96 fixed on of the issues by introducing appropriate links for the modules.

Semantic versioning: I understand the advantages and for most larger projects, this makes perfectly sense to me as well. However, in small projects, there are no bugfix releases and I do not differ between minor and major releases.

Instead, the information of the date seems much more interesting than any artificial number like 0.4.7 which does not hold any valuable information without a relation to a second version number. This is why I tend not to use semantic versioning for now.

If the modules are separated from the main framework, semantic versioning would be much more interesting and probably also a must-have since the separated modules would have to rely on a compatible framework with non-breaking changes for minor releases and potentially breaking changes only for major releases.