8.0.0

What's Changed

Breaking changes

• Remove PhoneNumberInternationalFallbackWidget by @francoisfreitag in #602

  Use phonenumber_field.widgets.RegionalPhoneNumberWidget instead.

• Move validation from widgets to the form fields by @francoisfreitag in #603

  Previously, the widgets were validating the phone number, leaving no room for the django regular validation procedure. If you performed custom validation on PhoneNumberFields, see the migration guide below.

Other changes

• Drop support for Django 4.1 by @francoisfreitag in #604
• docs: Fix representation of serializer by @francoisfreitag in #607

Full Changelog: 7.3.0...8.0.0

---

Migration guide

Previously, the widgets handled part of the validation. That behavior prevents overriding validation in form fields, as widgets were casting the value into a PhoneNumber object, validating it in the process.

Following the MultiValueField implementation from Django (and MultiWidget), the widget now handles the presentation logic, but makes
no attempt at validation. The new SplitPhoneNumberField handles the logic of validating the region choice and the number, and the PhoneNumberPrefixWidget simply dispatches the region and number data to the appropriate widget.

In order to retain backward compatibility, now that the validate_international_phonenumber actually comes into play, its error code has been changed to invalid, so that the custom error message for invalid shows.

validate_international_phonenumber

Review uses of the invalid_phone_number error code. You’ll probably want to replace them with invalid. Given that the validator usually did not come into play, you shouldn’t find many uses.

PhoneNumberField with RegionalPhoneNumberWidget

Move the custom validation occurs in the Django Form clean_FIELD() (or clean()), and no changes should be noticeable.

PhoneNumberField with PhoneNumberPrefixWidget

Use the SplitPhoneNumberField instead. Error messages will change slightly and should be more precise (whether the region is not part of
the choices, or the number cannot be interpreted in the selected region).

For more examples, take a look at tests.test_formfields.SplitPhoneNumberFieldTest.
Make sure GitHub loads the diff for file tests/test_formfields.py

The following tests should cover most use cases:

• test_custom_attrs before / after
• test_custom_choices before / after

7.3.0

What's Changed

• Add support for Django 5.0 by @adamchainz in #582
• Document phone number extension handling by @francoisfreitag in #583
• Make PhoneNumberPrefixSelect use the provided region by @francoisfreitag in #593
• Update Italian locale by @RuggeroFabbiano in #594

New Contributors

• @RuggeroFabbiano made their first contribution in #594

Full Changelog: 7.2.0...7.3.0

7.2.0

This release should have been an 8.0 by the semver, as the DB converter for the model field can break working code.

What's Changed

• BREAKING: Add a DB converter for the model field, fixing values_list() of PhoneNumberFields by @francoisfreitag in #559

• Use public attributes and methods from phonenumbers by @francoisfreitag in #535

• Remove zip_safe flag from setup.cfg by @francoisfreitag in #553

• feat: Add mypy to CI by @last-partizan in #563

• Drop support for Python 3.7 by @francoisfreitag in #561

• Show support for Python 3.11 by @francoisfreitag in #570

• Add support for Python 3.12 by @francoisfreitag in #576

New Contributors

• @dependabot made their first contribution in #555
• @last-partizan made their first contribution in #563

Full Changelog: 7.1.0...7.2.0

7.1.0

What's Changed

• Update Norwegian translations by @ddabble in #549
• Drop support for Django 4.0, add Django 4.2 by @francoisfreitag in #550

Miscellaneous

• Update python and Django matrix by @francoisfreitag in #548
• Add common virtualenv locations to flake8 exclude and .gitignore by @blaedd in #547
• Document E164 lack of support for phone extensions by @francoisfreitag in #537
• Strip trailing line from beautifulsoup prettify output by @francoisfreitag in #551

New Contributors

• @blaedd made their first contribution in #547
• @ddabble made their first contribution in #549

Full Changelog: 7.0.2...7.1.0

7.0.2

What's Changed

• Updated Swedish translations by @tjwalch in #544

New Contributors

• @tjwalch made their first contribution in #544

Full Changelog: 7.0.1...7.0.2

7.0.1

What's Changed

• Allow multiple DRF is_valid calls to succeed by @phillipuniverse in #543

New Contributors

• @phillipuniverse made their first contribution in #543

Full Changelog: 7.0.0...7.0.1

7.0.0

Possible backward incompatibilities

• RegionalPhoneNumberWidget becomes the default widget for the formfields.PhoneNumberField.
• The formfields.PhoneNumberField no longer sets the input_type attribute of its widget to tel. That behavior did not make sense for the existing PhoneNumberPrefixWidget and was dropped.
• PhoneNumberInternationalFallbackWidget will be replaced by RegionalPhoneNumberWidget in the next major version. It is deprecated until the next major release.

Changes

• Restore PhoneNumberPrefixWidget number input on form errors by @francoisfreitag in #520

  Fixes a bug where the form field prepare_value() transformed the PhoneNumber value to an str in the national format, but PhoneNumberPrefixWidget expects its value to be a PhoneNumber. formfields.PhoneNumberField now represents its value with a PhoneNumber object, giving widgets more control on how to display the value.

  That behavior prompted the change to PhoneNumberInternationalFallbackWidget becoming the default widget, to preserve the behavior established in 005769c. Switching to the widget allows users to opt-out from that behavior (e.g. by using a TextInput widget), whereas prepare_value() forced the conversion to the national string format.

• Set PhoneNumberInternationalFallbackWidget input_type to tel by @francoisfreitag in #521

  Previously, the <input> from the PhoneNumberInternationalFallbackWidget was set to text.

• Evolve PhoneNumberInternationalWidget to RegionalPhoneNumberWidget by @francoisfreitag in #529

  The newer widget gives more control over the display of phone numbers. The behavior of PhoneNumberInternaltionalWidget can be retained by setting PHONENUMBER_DEFAULT_FORMAT="INTERNATIONAL", which is why PhoneNumberInternaltionalWidget will be removed in the next major version.

• Add Dutch translation by @thijskramer in #532

• Add documentation and host it at readthedocs.org by @francoisfreitag in #531

• Prefer SUPPORTED_REGIONS over _AVAILABLE_REGION_CODES by @francoisfreitag in #528

New Contributors

• @thijskramer made their first contribution in #532

Full Changelog: 6.4.0...7.0.0

6.4.0

What's Changed

• Allow restricting PhoneNumberPrefixWidget country choices by @francoisfreitag in #525
• Handle empty input to PhoneNumberPrefixWidget by @francoisfreitag in #512
• Handle primitive types in serializerfields by @francoisfreitag in #523
• Implement region argument for serializerfields by @francoisfreitag in #519
• Fix CHANGELOG link to GitHub Releases by @adamchainz in #507
• Add compatibility with Django 4.1 by @francoisfreitag in #516
• Drop support for end-of-life Django 2.2 by @francoisfreitag in #515

New Contributors

• @adamchainz made their first contribution in #507

Full Changelog: 6.3.0...6.4.0

6.3.0

What's Changed

• Accept per-widget attrs for PhoneNumberPrefixWidget by @francoisfreitag in #502
• Drop Django 3.1 support by @francoisfreitag in #505

Full Changelog: 6.2.0...6.3.0

6.2.0

What's Changed

• PhoneNumberPrefixWidget improvement for regions sharing same country prefix by @amateja in #493
• Remove maxlength attribute for html5 compliance by @sterliakov in #490
• Better syntax highlighting by @bashu in #498
• Update Polish translation by @amateja in #500
• Update Lithuanian translations by @KiraLT in #390
• Update Portuguese translations by @AndreMorais98 in #504

New Contributors

• @bashu made their first contribution in #498
• @KiraLT made their first contribution in #390
• @sterliakov made their first contribution in #490
• @AndreMorais98 made their first contribution in #504

Full Changelog: 6.1.0...6.2.0