examples: create examples structure and add first example

[whooo]

This is a starting point for example usage of the different APIs, starting with a basic example of using ESAPI.

My plan is to add more examples over time which somewhat should cover real world use cases while being readable.

[whooo]

@niooss-ledger, could you have a look and see if you think this can close #298

[williamcroberts]

I wonder if we should mention in the ESYS_TR class documentation that to go from a TPM2_HANDLE to an ESYS_TR you should use tr_from_public.

[codecov]

Codecov Report

Merging #317 (6bec769) into master (235c439) will decrease coverage by 0.01%.
The diff coverage is 94.11%.

@@            Coverage Diff             @@
##           master     #317      +/-   ##
==========================================
- Coverage   93.54%   93.53%   -0.02%     
==========================================
  Files          15       15              
  Lines        4662     4699      +37     
  Branches      590      600      +10     
==========================================
+ Hits         4361     4395      +34     
- Misses        218      224       +6     
+ Partials       83       80       -3     

Impacted Files	Coverage Δ
tpm2_pytss/internal/crypto.py	92.36% <0.00%> (-1.77%)	⬇️
tpm2_pytss/types.py	95.43% <25.00%> (-0.10%)	⬇️
tpm2_pytss/ESAPI.py	98.10% <100.00%> (+0.16%)	⬆️
tpm2_pytss/constants.py	99.27% <100.00%> (+0.02%)	⬆️
tpm2_pytss/tsskey.py	98.34% <100.00%> (ø)
tpm2_pytss/TCTILdr.py	93.75% <0.00%> (+6.25%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7338869...6bec769. Read the comment docs.

[whooo]

I wonder if we should mention in the ESYS_TR class documentation that to go from a TPM2_HANDLE to an ESYS_TR you should use tr_from_public.

Wouldn't hurt, I can create another PR for that.

[niooss-ledger]

Thanks for this PR! I agree this would be a nice way to close #298 :)

I added some comments. Also, the example does not work as-is on a TPM I am using, due to an issue that I reported in #318, but when I work around this issue, I managed to run it. And the code of the example is easy to understand :)

[williamcroberts]

I have mixed feelings about example code as well, it's often times left to rot, plus how do we know if something we do breaks an example. We need to figure out a way to get this into our test suite.

[whooo]

I have mixed feelings about example code as well, it's often times left to rot, plus how do we know if something we do breaks an example. We need to figure out a way to get this into our test suite.

I worry about the rot as well and I think having good tests might be hard as some of the examples I plan on writing will require extra dependencies.
I'm open to having the examples in another git repository (for example directly under my user on github) with a big warning about testing/compatibility

[williamcroberts]

I have mixed feelings about example code as well, it's often times left to rot, plus how do we know if something we do breaks an example. We need to figure out a way to get this into our test suite.

I worry about the rot as well and I think having good tests might be hard as some of the examples I plan on writing will require extra dependencies. I'm open to having the examples in another git repository (for example directly under my user on github) with a big warning about testing/compatibility

Wouldn't they just be dev dependencies? As long as you can pip install and add them to the dev section, I don't really care.
We've also talked about having more tutorials and stuff under our github io page, so that's an option too, or we could embed them in the docs as a tutorials section for just pytss. I'm pretty open to ideas here, and not really invested in any one way.

[whooo]

I worry about the rot as well and I think having good tests might be hard as some of the examples I plan on writing will require extra dependencies. I'm open to having the examples in another git repository (for example directly under my user on github) with a big warning about testing/compatibility

Wouldn't they just be dev dependencies? As long as you can pip install and add them to the dev section, I don't really care. We've also talked about having more tutorials and stuff under our github io page, so that's an option too, or we could embed them in the docs as a tutorials section for just pytss. I'm pretty open to ideas here, and not really invested in any one way.

Putting the dependencies under dev should be enough for now.
I added a test for the first example, I didn't add full coverage as I don't think it's needed but I might be wrong

[iolivergithub]

FYI, I've started putting examples up at: https://github.com/tpm2dev/tpm.dev.tutorials/tree/master/PythonExamples
Feel free to use

[williamcroberts]

I think if we have examples, to ensure they are complete they should run with the test harness, i'm sure we could plumb them in somehow.

[whooo]

I'll close this for now, might revisit it in the future