Contributions?

[tobiasbp]

Hello there....

I was about to refactor an age old Python2 project for the deprecated v1 FreeNAS API when I found this project via pypi.org (I was planning on making a package).

Would you be interested in contributions? And, perhaps some guidance, since your wrapper is built a lot better than my age old python2 implementation.

I'd like to add support for datasets, shares and permissions. I'm using my current v1 wrapper for the automated setup of dataset backed time machine-shares for MacOS users.

[sdwilsh]

I'm totally open to contributions. My primary purpose of this is to set it up for an integration I'm working on for Home Assistant (in sdwilsh/hass-freenas). For my immediate needs, I just wanted disks and vms, but I figured support would be added for things as folks wanted to either contribute or ask and I had time :)

Work has been a bit busy this week for me, so my bandwidth will be limited to help, but based on the api, it looks like you might want to focus on adding support for pools first, before tackling datasets. Shares looks fairly straight forward as well as user pemrissions.

I'll leave this issue open so we can coordinate for now :)

[tobiasbp]

Sounds good. I have been studying your code, and I feel I have understood most of it. I like the use of typing and descriptors.

I'm unsure where the parameters in the following come from. I can't seem to match the content of the list in select to the documentation (Which is unfamiliar to me as I'm used to reading documentation on RESfulT APIs). Maybe you can point me in the right direction?

     disks = await self._client.invoke_method(
            "disk.query",
            [
                [],
                {
                    "select": [
                        "description",
                        "model",
                        "name",
                        "serial",
                        "size",
                        "type",
                    ],
                },
            ],
        )

I'll try to add support for pools first, as you suggest.

Also, could you comment on how to perform tests?

[sdwilsh]

I like the use of typing and descriptors.

This is my first python project in many, many years, so it was for my own sanity ;)

I'm unsure where the parameters in the following come from.

This was, by far, the most difficult part I've dealt with. Their API docs are not easy to understand, IMO. For getting the pools, I imagine you'd want to use pool.query. Each box under the arguments represents a schema for the argument.

As best I can tell, argument one (query-filters) takes only an array of null. This is just like disk.query, so you can see I just passed [] as the first argument for that.

The second argument (query-options) has a bunch of things to let you modify what is queried. I could speculate on most of them, but don't really know for sure because I have not played with them.

I can't seem to match the content of the list in select to the documentation

Their documentation leaves a lot to be desired. What I did was ran a query without the select section first, and saw everything that was returned. From there, I limited the response to what I wanted with the select.

I found writing a test script, and then calling machine._client.invoke_method in it helped me play around with things to get a sense of what the server would actually return.

[tobiasbp]

This was, by far, the most difficult part I've dealt with. Their API docs are not easy to understand, IMO.

Agreed. It's not just me then. Phew... :)

Their documentation leaves a lot to be desired. What I did was ran a query without the select section first, and saw everything that was returned. From there, I limited the response to what I wanted with the select.

OK. That was the approach I was planning on using too.

I'll start on a branch for implementing support for pools.

Thank you for your time.

[sdwilsh]

@tobiasbp, I productionized the test script I was using to play around with things, and added a section in README.md to document it (plus there's always -h). It should help you out when playing with method invocation, I hope!