Finalize and document Tracker API

[godlygeek]

Closes: #25

Rendered documentation can be previewed here.

@pablogsal Let me know whether there's anything else that you'd like to see documented here.

Now is probably our last chance to rename some of this before the API actually gets users. I'm wondering whether we should have gone with force=True or overwrite=True for the parameter to tell a FileDestination to overwrite an existing file, instead of exist_ok=True. I'm also thinking that the name SocketDestination is a bit odd for something that configures how to start a server, rather than a client...

[pablogsal]

@pablogsal Let me know whether there's anything else that you'd like to see documented here.

I wonder if we want to document the FileReader and related classes, as they are part of the API and those are the ones that allow extension. I think is important to document these because part of the power of custom inspection comes from here and this is what can unlock a much better community of plugins and whatnot.

[pablogsal]

I'm wondering whether we should have gone with force=True or overwrite=True for the parameter to tell a FileDestination to overwrite an existing file, instead of exist_ok=True. I'm also thinking that the name SocketDestination is a bit odd for something that configures how to start a server, rather than a client...

I agree with both, those are good points. What about if we rename exists_ok to overwrite?

Regarding SocketDestination is a bit trickier because we are indeed sending this to a socket destination, but the whole enterprise then makes the whole program act as a server. I think that is ok-ish unless some other native speakers think otherwise.

[godlygeek]

I wonder if we want to document the FileReader and related classes, as they are part of the API and those are the ones that allow extension.

I've gone with "no" for now, in part because we haven't yet gotten any requests for this, but also because I'm not as familiar with those classes and I can't speak as well to whether we're willing to commit to interface stability on them, or whether there's things that still need to be revisited.

Regarding SocketDestination is a bit trickier because we are indeed sending this to a socket destination,

Yes, but the destination that we send to isn't identified by the host and port that you give. You do Tracker(SocketDestination(port=1234)), and we don't send any data to port 1234. Instead, we listen on port 1234 for an incoming connection, which gets assigned an ephemeral port, and we send data to that ephemeral port instead.

I dunno - I find the name a bit misleading, but I also can't really think of a way to fix it. I guess we could call it SocketServer instead...

I agree with both, those are good points. What about if we rename exists_ok to overwrite?

Ack, I'll make that change.

[pablogsal]

I guess we could call it SocketServer instead...

SocketServer works for me

[godlygeek]

After some offline discussion, we've settled on leaving SocketDestination for the name of that class, but changing its constructor parameters to make it clearer that it's spawning a server, renaming

class memray.SocketDestination(port: int, host: str = '127.0.0.1')

to

class memray.SocketDestination(server_port: int, address: str = '127.0.0.1')