Create a module for the frontend of the endpoint function

[akash5100]

Fixes #27

[codecov-commenter]

Codecov Report

Merging #33 (acaa047) into main (2953bb3) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##              main       #33   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         6    +2     
  Lines           59        79   +20     
=========================================
+ Hits            59        79   +20     

Impacted Files	Coverage Δ
hvpy/api_groups/jpeg2000/get_jp2_image.py	100.00% <ø> (ø)
hvpy/facade.py	100.00% <100.00%> (ø)
hvpy/utils.py	100.00% <100.00%> (ø)

---

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 2953bb3...acaa047. Read the comment docs.

[akash5100]

current code result:

    Retrieve a JP2000 image from the helioviewer.org API.

    Attributes
    ----------
    date : datetime.datetime
        Desired date/time of the JP2 image.
    sourceId : int
        Unique image datasource identifier.
    jpip : bool, optional
        Returns a JPIP URI instead of the binary data of the image if set to `True`, defaults to `False`.
    json : bool, optional
        Returns the JSON if set to `True`, defaults to `False`.

    References
    ----------
    * `<https://api.helioviewer.org/docs/v2/api/api_groups/jpeg2000.html#getjp2image>`__
    
    Example:

        >>> getJP2Image(date=datetime(2019,1,1), sourceId=1, jpip=True)
        'jpip://helioviewer.org:8090/EIT/2013/08/07/195/2013_08_07__01_13_50_146__SOHO_EIT_EIT_195.jp2'

[dgarciabriseno]

This is what I would call arcane magic code. Difficult to read. It enforces a strict code style on docstrings, but no one would know the style enforcement exists unless they knew this code exists and read it first.

As I understand it, it reads something like:
Start with a new line
Take the 2nd & 3rd lines from the wrapped function’s doc string
Insert the data from the 3rd line on from the input class’s doctoring
Take the remaining lines from the wrapped function’s docstring.

This will be error prone if we forget to follow these string line numbers while writing comments. It's too strict.

Don't split by new line characters, we can't easily enforce that a docstring is only one line long. Put markers in the comment instead.

For example, for getJP2Image add something like this

"""
    Retrieve a JP2000 image from the helioviewer.org API.

    {{Insert Shared Docstring}}

    Example:
        >>> getJP2Image(date=datetime(2019,1,1), sourceId=1, jpip=True)
        'jpip://helioviewer.org:8090/EIT/2013/08/07/195/2013_08_07__01_13_50_146__SOHO_EIT_EIT_195.jp2'
    """

And in getJP2ImageInputParameters add something like

"""
Words words words about input parameters

{{Shared}}
Attributes
-----
...

References
----
...
{{End Shared}}

Then _copy_docstring can extract the text between {{Shared}} and {{End Shared}} and insert into the docstring at {{Insert Shared Docstring}}. This gives us more control about the docstrings being shared, and for anyone writing docstrings, they will see these markers in other docstrings and will know there's some post processing going on to adhere to.

And it doesn't force us to stick to specific line numbers.

[akash5100]

Great idea, easy, clean. But this will affect documentation for <endpoint>InputParameters,
See the docs below that I tried to build using this.

[dgarciabriseno]

I suppose we could make another decorator that clears these out. Or instead of {{Shared}} we can use other less intrusive markers.

[nabobalis]

I wonder if this is why the sunpy version is more complex.

We could just copy that function wholesale and hope that is enough to get this working?

[nabobalis]

Ah no, the sunpy function doesnt do what I thought it did. Ignore me.

[akash5100]

I suppose we could make another decorator that clears these out.

If we do this, the docstring of the <endpoint>InputParameters class will get updated at runtime, and we will lose {{Shared}} and {{End Shared}} and the other decorator (_copy_docstring) will not be able to find them.

[nabobalis]

I pushed a change that I think solves the problem expect one.

[akash5100]

Which problem is left?

[nabobalis]

https://hvpy--33.org.readthedocs.build/en/33/api/hvpy.getJP2Image.html#hvpy.getJP2Image

The attributes are named hvpy.date instead of date

[dgarciabriseno]

This is what I would call arcane magic code. Difficult to read. It enforces a strict code style on docstrings, but no one would know the style enforcement exists unless they knew this code exists and read it first.

As I understand it, it reads something like:
Start with a new line
Take the 2nd & 3rd lines from the wrapped function’s doc string
Insert the data from the 3rd line on from the input class’s doctoring
Take the remaining lines from the wrapped function’s docstring.

This will be error prone if we forget to follow these string line numbers while writing comments. It's too strict.

Don't split by new line characters, we can't easily enforce that a docstring is only one line long. Put markers in the comment instead.

For example, for getJP2Image add something like this

"""
    Retrieve a JP2000 image from the helioviewer.org API.

    {{Insert Shared Docstring}}

    Example:
        >>> getJP2Image(date=datetime(2019,1,1), sourceId=1, jpip=True)
        'jpip://helioviewer.org:8090/EIT/2013/08/07/195/2013_08_07__01_13_50_146__SOHO_EIT_EIT_195.jp2'
    """

And in getJP2ImageInputParameters add something like

"""
Words words words about input parameters

{{Shared}}
Attributes
-----
...

References
----
...
{{End Shared}}

Then _copy_docstring can extract the text between {{Shared}} and {{End Shared}} and insert into the docstring at {{Insert Shared Docstring}}. This gives us more control about the docstrings being shared, and for anyone writing docstrings, they will see these markers in other docstrings and will know there's some post processing going on to adhere to.

And it doesn't force us to stick to specific line numbers.