search

pyinfra-dev / pyinfra

pyinfra turns Python code into shell commands and runs them on your servers. Execute ad-hoc commands and write declarative operations. Target SSH servers, local machine and Docker containers. Fast and scales from one server to thousands.
https://pyinfra.com
MIT License
3.91k stars 383 forks source link

API change `name` arg #395

Closed pylang closed 4 years ago

pylang commented 4 years ago

Is your feature request related to a problem? Please describe.

This is a minor observation, but the name parameter in operations seems confusing.

Example:

apt.package(
    name="Ensure package is installed"
    ...
)

Expecting a name, instead we seem to pass in a phrase or title. I'm not familiar with conventions, but I wasn't sure what "name" to pass in until I saw examples.

Describe the solution you'd like

Since API changes are being considered with v1.1, I suggest changing the name of the parameter name to fit its purpose, e.g. title, or comment, etc. This may help newcomers infer what should be passed in.

Fizzadar commented 4 years ago

To me the argument is simply to "name the operation". I think title/description/comment would all be just as valid too (I considered description but chose name as it's quicker to type). A name can be one or more words and is essentially a form of identifier for a given object (operation call in this case).

Also important to note is its entirely optional to provide the name argument and only serves as a prettified/humanised name for an operation call. Perhaps it could be removed from the examples? The behaviour without still outputs all the relevant information.

As for changing the argument that would be a breaking change (v2) and given the above I don't see any reason to change it, am open to opinions on this for the future (potential to implement a new name for 1.1 with backwards compatibility if there's lots of weight behind it).