use literalinclude in code-style-linting-format #259

ucodery · 2024-05-20T15:50:31Z

No description provided.

ucodery · 2024-05-20T16:20:53Z

Tagging #250

lwasser

@ucodery i think i just need you to help me understand how this is implemented? i think the idea is super cool. i just don't fully understand how a user will interact with the code samples and pre commit hooks in our guidebook. Thank you for this!! it's really great to have more real world examples here and frankly the stravalib examples are way to complex for our goals in this guidebook!

lwasser · 2024-05-30T23:58:07Z

examples/pure-hatch/.pre-commit-config.yaml

+    hooks:
+      - id: flake8
+
+# Black for auto code formatting


@ucodery i've been thinking a bit about what code formatters we want to recommend. I know we suggested black and flake8 but that was last year! it seems to me a lot of people are using ruff these days! we just moved to it at stravalib a few months ago.

do you think we should consider a future issue / task for the future of suggesting ruff in place of these since it does so many things and creates a simpler / faster config?

I have also moved a few project to ruff this year. I think it is a great tool, and like hatch it enmpaases a lot of tasks that previously required a medley of tools and decisions by users, which can be great for beginners. I think we should however raise this in a new issue/ discussion.

lwasser · 2024-05-30T23:58:18Z

examples/pure-hatch/.pre-commit-config.yaml

+  rev: 22.12.0
+  hooks:
+  - id: black
+    language_version: python3.8


Suggested change

language_version: python3.8

language_version: python3.10

I was just porting the examples as they were originally written.

lwasser · 2024-05-30T23:59:04Z

examples/pure-hatch/pyproject.toml

@@ -36,3 +36,14 @@ docs = [
    "sphinx",
    "pydata-sphinx-theme"
 ]
+
+[tool.ruff]


oh.. i may be confused. here you do have ruff. please help me understand this config!

Yes, the guide originally had examples for both black and ruff, in different sections, as it covers both. There is nothing wrong about having a pyproject.toml with both, the project will work just fine (although yes, confusing) even if the tools are set up to use conflicting settings. The tool table is just a place to stick settings. It makes no guarantees or standards about what tools are chosen or how they interact or anything.

lwasser · 2024-05-31T00:00:19Z

examples/pure-hatch/src/examplePy/temperature.py

+    Parameters:
+        celsius (float): Temperature in Celsius.
+
+    Returns:
+        float: Temperature in Fahrenheit.


we prefer to use numpy style docstrings and suggest that in our guidebook.

jeremy, i think i understand what you are doing - in terms of having things in "other" formats. so you can likely ignore ALL of my inline suggestions -- BUT i don't understand how it's implemented in the guidebook. if you can give me instructions on how this would be run or how someone interacts with it that would be great!!

I was not trying to be different, again I just ported the examples as they already existed.

lwasser · 2024-05-31T00:00:33Z

examples/pure-hatch/src/examplePy/temperature.py

+
+def fahrenheit_to_celsius(fahrenheit):
+    """
+    Convert temperature from Fahrenheit to Celsius.


please use numpy style here and throughout! thank you!

here are you showing other docstring formats? will those be used elsewhere in our guidebook?

lwasser · 2024-05-31T00:01:27Z

examples/pure-hatch/src/examplePy/temporal-raw.py

+from examplePy.temperature import fahrenheit_to_celsius
+import pandas
+from typing import Sequence


I think if we follow isort / pep8 we'd want examplePy to be the last import?

or were you doing this intentionally to allow isort to take action is a user tries to run it?

I did this intentionally in order to make a counter example. Notice that this module is named temporal-raw (illegal python name, not allowed as an import target) while the package also has same-but ordered module named temporal.

lwasser · 2024-05-31T00:02:16Z

examples/pure-hatch/src/examplePy/temporal-raw.py

+
+def calc_annual_mean(df: pandas.DataFrame):
+    """Function to calculate the mean temperature for each year and the final mean"""
+    # TODO: make this a bit more robust so we can write integration test examples??


Is this a comment from me? i kind of recall talking about tests but also we could potentially remove the todo here in the example package?

Yeah, this is from you 😄 ec0255c4

lwasser · 2024-05-31T00:02:25Z

examples/pure-hatch/src/examplePy/temporal-raw.py

@@ -0,0 +1,15 @@
+from examplePy.temperature import fahrenheit_to_celsius
+import pandas


Suggested change

import pandas

import pandas as pd

lwasser · 2024-05-31T00:02:50Z

examples/pure-hatch/src/examplePy/temporal-raw.py

+import pandas
+from typing import Sequence
+
+def calc_annual_mean(df: pandas.DataFrame):


Suggested change

def calc_annual_mean(df: pandas.DataFrame):

def calc_annual_mean(df: pd.DataFrame):

or just import DataFrame from pandas above?

lwasser · 2024-05-31T00:04:49Z

package-structure-code/code-style-linting-format.md

-from stravalib import exc
-from stravalib import unithelper as uh
-```
+:::{literalinclude} ../examples/pure-hatch/src/examplePy/temporal.py


ahhhh i think this answers my question above about the imports. i haven't run this locally. maybe you can help me understand what will happen here in our guidebook with code examples that have formatting issues. will isort run? or would we tell the user to have it run as a small demo that they could implement?

nothing runs, literalinclude takes the contents of some file (temporal.py) and replaces the directive with those contents somewhere between reading the md file and producing the final html. It is just a way to organize content apart from markdown files. Especially re-used content.

lwasser · 2024-05-31T00:10:53Z

ok i see now @ucodery IGNORE all of my comments. this looks great. I think i have one request but i'm not sure how to implement this. What you are adding is really cool. essentially someone can test out how linters work.

i feel like we want instructions around doing this. I also feel like we could ask some of the myst folks about better ways to make it more clearly interactive. because what you have done here is really really great.

so take aways

let's merge this! ignore my review. i now feel silly that i left those comments.
how can we call more attention to the fact that you're adding more interactive activities to the page (which is awesome)?? -- in a separate issue we could discuss.

ucodery · 2024-05-31T16:49:43Z

A few clarifications:

These example projects are not yet full projects (I think any would build, but e.g. pure-hatch contains no python code right now). #248 is open for getting us to multiple really usable example projects.

These literalinclude PRs I've been making are just the first steps and are only about moving toml and python code that already existed in markdown into their own files; like taking a jupyter monolith and extracting some pure python modules.

I'm not trying to make any drastic changes, and I consider it a success when I make 0 changes to the rendered site after literalinclude. So although I agree that the python world has moved fast and a lot has changed in just the last year, I think those changes should be considered in separate issues.

As for how readers will interact with these examples, right now they are still just code blocks in the guide. Nothing here makes examples runnable. In order to test any of it out a reader would likely have to clone the repo and cd to the example and use CLI/ IDE to play around; they might even have to copy out the example code into a new project, to test git hooks for example.

lwasser

thank you for this @ucodery i appreciate your patience with my (really off base review). i think i lost track of the scope of what you are doing. let's merge this!!

ucodery added 2 commits May 20, 2024 08:40

use literalinclude in code-style-linting-format

d5bae11

fixup: language tag

7ebb86b

lwasser added the sprintable label May 21, 2024

lwasser added the pyconus-24 label May 29, 2024

lwasser reviewed May 31, 2024

View reviewed changes

lwasser approved these changes May 31, 2024

View reviewed changes

lwasser merged commit 2d7402b into pyOpenSci:main May 31, 2024
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

use literalinclude in code-style-linting-format #259

use literalinclude in code-style-linting-format #259

ucodery commented May 20, 2024

ucodery commented May 20, 2024

lwasser left a comment

lwasser May 30, 2024

ucodery May 31, 2024

lwasser May 30, 2024

ucodery May 31, 2024

lwasser May 30, 2024

ucodery May 31, 2024

lwasser May 31, 2024

lwasser May 31, 2024

ucodery May 31, 2024

lwasser May 31, 2024

lwasser May 31, 2024

lwasser May 31, 2024

ucodery May 31, 2024

lwasser May 31, 2024

ucodery May 31, 2024

lwasser May 31, 2024

lwasser May 31, 2024

lwasser May 31, 2024

ucodery May 31, 2024

lwasser commented May 31, 2024

ucodery commented May 31, 2024

lwasser left a comment

		@@ -0,0 +1,15 @@
		from examplePy.temperature import fahrenheit_to_celsius
		import pandas

	def calc_annual_mean(df: pandas.DataFrame):
	def calc_annual_mean(df: pd.DataFrame):

use literalinclude in code-style-linting-format #259

use literalinclude in code-style-linting-format #259

Conversation

ucodery commented May 20, 2024

ucodery commented May 20, 2024

lwasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lwasser commented May 31, 2024

ucodery commented May 31, 2024

lwasser left a comment

Choose a reason for hiding this comment