search

ianklatzco / atprototools

easy-to-use and ergonomic library for interacting with bluesky
MIT License
62 stars 11 forks source link

Made method names consistent and added docstrings #24

Closed BSculfor closed 1 year ago

BSculfor commented 1 year ago

Closes Issue #12. I know most of the method names are self-documenting, but it doesn't hurt to have docstrings anyway. The second commit changes the names in test_main.

P.S. I'd like to be able to make some more substantive changes, but I don't have a bluesky account. If you have a spare invite I'd appreciate it.

ianklatzco commented 1 year ago

Amazing, thank you!

Would you be so kind as to change them to thisCase so they're consistent with the case in atproto? I'll send 2 invites your way if so ^^

BSculfor commented 1 year ago

I'd figured that snake_case was better because it fits python conventions, even if it diverges from atproto. Part of the point of this project (as I see it) is that the user shouldn't need to know the details of atproto, and it's easy enough to work out the API method name from the python method name in these cases. All of the Session methods are python methods, but only some correspond to distinct API methods, so it makes sense to me to stick to python conventions for all of them. Perhaps use snake_case for the Session methods and camelCase for the methods of the proposed APIAction class?

Ultimately it's your project though, and I can definitely see why it would be desirable. While I'm doing this, should I make some of the other names closer to the atproto names (e.g. get_skyline to getTimeline)?

ianklatzco commented 1 year ago

all good considerations!

i was hoping this library could be friendly / easy-to-use. there's now https://github.com/marshalX/atproto which is a more-full-fledged library, so i think the role of this one will be "utility functions", "REPL for your skeets", "teaches you the names+cases of the xrpc endpoints", "friendly", and "easy to use".

to that end i think consistent camelCase across the board is probably best, if you'd be so kind 🙏

ianklatzco commented 1 year ago

made the changes myself! thanks for motivating me ^^

shoot me an email - iklatzco AT gmail - for a pair of invite codes ^^

ntindle commented 1 year ago

I know I have no say here, but I'd like to voice that following the language guidelines is probably a good idea, as stated in pep-0008 https://peps.python.org/pep-0008/#method-names-and-instance-variables

Lots of tools will throw a fit if this isn't matched.

ianklatzco commented 1 year ago

Hmmm that's quite a tempting consideration, thanks for sharing -- PEP8 is pretty canonical, right?

I suspect https://github.com/marshalX/atproto is probably pep8 and worth being canonical - i think i intend for atprototools to serve more of the "getting started as quick as possible" wrapper library ^^

davidcarryer commented 1 year ago

PEP8 is pretty solid. Worth consideration. Building on a standard, especially a Python Standard, makes good sense.

BSculfor commented 1 year ago

I know I have no say here, but I'd like to voice that following the language guidelines is probably a good idea, as stated in pep-0008 https://peps.python.org/pep-0008/#method-names-and-instance-variables

Yes, PEP8 was what I was referring to when I said "snake_case fits python conventions" in my earlier comment, it's The Standard for python. All the auto-formatting tools (including autopep8 that you recommended using when contributing to the project) are minor variations of PEP8 (usually just having less strict limits on line length).

I stand by my earlier suggestion that we could have something like a APIAction or RawSession class which follows the AT protocol/xrpc closely, so:

We'd keep the Session class as a more usable utility version that:

Then RawSession would be used by people who really want to grapple with AT protocol, and the Session can be used by people who just want to write a bot or do something quick. The details would still need to be sketched out, e.g. do we have an APIAction class where the xrpc methods are instances, or a RawSession class where xrpc methods are methods, but this presents a compromise between teaching Lexicon/AT protocol/xrpc and having a pythonic interface (in both naming and usage).