Should env.url return a string instead of a urllib.parse.ParseResult?

[sloria]

the current typing assumes that default is the same type as the "internal type" returned by the parser method. for url, that's a urllib.parse.ParseResult.

therefore, to pass type-checking, you'd need to do:

from typing import reveal_type
from urllib.parse import urlparse

from environs import env

MY_API_URL = env.url(
    "MY_API_URL",
    default=urlparse("http://api.example.com"),
)

print(reveal_type(MY_API_URL))
# Runtime type is 'ParseResult'

If you want a string, you can use env.str with the URL validator.

from typing import reveal_type

from environs import env, validate

MY_API_URL = env.str(
    "MY_API_URL",
    default="http://api.example.com",
    validate=validate.URL(),
)

print(reveal_type(MY_API_URL)) 
# Runtime type is 'str'

i've updated the docs to clarify this.

so while the current behavior is expected, perhaps it isn't desired. should env.url just return a string and do validation? i'm not sure how many users want a ParseResult 🤔 . i'll open a new issue for this to gather feedback.

Originally posted by @sloria in #400

[ddennerline3]

I think the previous behavior where a string was acceptable and converted into parsed components. The current behavior where the default="http://www.example.com" returns a string breaks API compatibility.

This sequence below worked correctly and now breaks. We have the unparse call scattered all over the code.
Maybe a new env.url2() that just validates the URL stringb and keeps it as a string would provide best balance IMHO.

MAIN_URL = env.url("MAIN_URL", "https://www.example.com/v1/widget")
def get_widget():
       endpoint = urlunparse(MAIN_URL)
       requests.get(endpoint + f"/{id}")

[sloria]

@ddennerline3 for your use case, would it be better if env.url returned a string (and use urllib.parse.urlparse when you actually need a ParseResult)?

changing the return value would be a breaking change, but I wonder if it's a more user-friendly default. i personally haven't run into a use case where i need the URLs in my settings to be ParseResults