Python import mappings documentation

[ctrlaltdylan]

Adds a dedicated page under the Python documentation to show a reference of all available Python custom mappings and a request form to add new ones.

The new page path is:

/docs/code/python/import-mappings/

Possible improvements

• Better copy / explaination of why Python mappings are needed?
• Better title?

To Dos

✅ Show a better success message when submitting a new package request
✅ Case insensitivity on the search

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
pipedream-docs	✅ Ready (Inspect)	Visit Preview	Apr 27, 2022 at 4:16PM (UTC)
pipedream-docs-redirect-do-not-edit	✅ Ready (Inspect)	Visit Preview	Apr 27, 2022 at 4:16PM (UTC)

[dylburger]

This is cool but I have a couple of concerns:

• It reads like this is a searchable list of all packages, but pipreqs actually implements this logic: 1) search for the import name on PyPI, and if a package with that name doesn't exist, 2) look up the import name in the mapping file to see if a mapping exists. So this isn't a full list of packages, just the list for # 2.
• Do you have a plan for keeping this list up-to-date with the list in the EE in prod?

[dylburger]

It might be nice to note to the user that all they have to do is import package and it should just work (the user doesn't really need to know whether pipreqs finds the package or has to look it up from the mapping file).

Then we can tell the user: if import package doesn't work, they can fill out the request for us to add support for the package. But we technically don't need to tell them that there's a mapping file involved at all. It's not a secret, but I think it overcomplicates the explanation, since we'll still tell them to import package once we add the mapping anyway. wdyt?

[dylburger]

Since you had asked about how to better explain the mappings, I commented on that section specifically. I don't think you need to talk about mappings at all and can frame to the user as:

1. Just import package
2. If that fails, request support for the package with the new form you added

Then I think you can remove the list of mappings entirely.

I forgot we actually had language on this here: https://pipedream-docs-git-docs-python-mappings-pipedreamers.vercel.app/docs/code/python/#if-your-package-s-import-name-differs-from-its-pypi-package-name

So you can probably just move your form to that section!

[ctrlaltdylan]

@dylburger Thanks, I didn't realize we had a small section on the main Python README.

Do you have a plan for keeping this list up-to-date with the list in the EE in prod?

You might have been out for the demo I gave the other day. But there's a workflow that listens to changes on the pipedreamin python mappings file and generates a JSON blob of this new data.

https://pipedream.com/@pd-support/python-mappings-database-p_NMC7Jam/inspect

That's how I was going to keep these in sync automatically.

Then I was going to have a workflow automatically commit the JSON blob as a file.

Then we can tell the user: if import package doesn't work, they can fill out the request for us to add support for the package. But we technically don't need to tell them that there's a mapping file involved at all. It's not a secret, but I think it overcomplicates the explanation, since we'll still tell them to import package once we add the mapping anyway. wdyt?

My concern is that the natural flow of a Python user will be:

1. Try the normal mapping, i.e. from ShopifyAPI import shopify and the import fails
2. The user searches Google for "Pipedream import ShopifyAPI" and there's no specific result to help them
3. They give up or make a ticket

Searching for "Pipedream import mapping" is covered by this article which is good, but I don't see the harm in covering more Python content.

We can reduce the explanation if needed. But the end goal was to help the DX be more self serving.

Also noted on the search difference from PyPI, I could replace this JSON blob with a Algolia index for proper searching, but I thought this would be an MVP to start.